Observability / Basic: signals and measurement meaning / Lesson 2

Metric types, units, and temporality

Choose instruments according to what a quantity means, then preserve units, aggregation, and cumulative or delta semantics through collection and queries.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Distinguish event counts from current values.
Interpret cumulative and delta points.
Review units and additive dimensions.

Choose by semantics rather than appearance

A counter records increments for a quantity that accumulates, such as accepted parcel scans. A current queue depth can rise or fall and needs an instrument that represents that behavior. A histogram records a distribution of measurements such as processing duration. OpenTelemetry distinguishes synchronous and asynchronous instruments and their permitted aggregation meanings; language SDK support must be checked for the actual version. Do not choose an instrument merely because its graph resembles the desired dashboard. Write the quantity, unit, update method, and intended aggregation first, then select a supported instrument that preserves that meaning.

Make units part of the contract

A duration of 250 means little until the unit is known. Converting milliseconds to seconds at one stage but retaining the old unit label creates a thousandfold error without changing the graph’s shape. Keep naming, metadata, documentation, and query display consistent. Avoid mixing currencies, byte counts, and durations under one metric family. Attributes should identify comparable observations, such as a bounded operation type, rather than change the measurement’s physical meaning. The editorial record below describes one duration instrument; it is not an SDK declaration or a semantic-convention guarantee for every runtime.

yaml Illustrative duration contract

quantity: parcel-processing-duration
unit: seconds
measurement: processing-end-minus-processing-start
instrument_shape: histogram
attributes: [bounded-operation-type, bounded-result-class]
excluded_attributes: [parcel-id, customer-email]

The record fixes quantity and units before choosing an implementation. It creates no instrument or time series.

Distinguish a total from an interval delta

A cumulative point summarizes from a start time, while a delta point summarizes a particular interval. Summing successive cumulative values double-counts earlier events. The offline fixture starts with cumulative counts of ten, fifteen, and twenty-one and derives interval increases of five and six between observations. It assumes one uninterrupted sequence. If a process restarts, a lower cumulative count is not a negative event rate; reset handling and start-time metadata matter. A collector or exporter may transform temporality, so review the complete path rather than assuming the backend sees the SDK’s original representation.

python Offline cumulative-to-delta reasoning

cumulative = [10, 15, 21]
deltas = [current - previous for previous, current in zip(cumulative, cumulative[1:])]
print(deltas)
print("incorrect_sum", sum(cumulative))
print("observed_increase", cumulative[-1] - cumulative[0])

Expected output

[5, 6]
incorrect_sum 46
observed_increase 11

The observed increase is 11 after the first observation; the initial 10 occurred before that comparison boundary. No counter reset is modeled.

Check whether addition is meaningful

Adding accepted-event counts across disjoint workers can produce a service total if the same event is not counted by several workers. Adding temperatures or averaging already aggregated percentiles does not have the same meaning. For current values, decide whether sum, maximum, or another operation answers the question: total queue depth and worst queue age describe different risks. Preserve the source population and aggregation boundary. An instrument can be technically accepted by an SDK while still representing a misleading quantity. Review representative events and intended queries together before publishing a metric contract.

Version semantic changes deliberately

Changing a unit, event boundary, attribute meaning, or temporality can break comparisons even when the metric name stays unchanged. Treat it as a contract migration: document old and new semantics, update consumers, and retain a clear transition point. Avoid silently combining incompatible histories. Test representative increments, current-value changes, zero activity, and restart cases with a small local fixture before relying on a query. This lesson executes only pure arithmetic; no OpenTelemetry SDK, collector, metrics backend, or running application is configured or tested.

Common errors and fixes

Summing counter snapshots inflates traffic

Why it happens: Cumulative totals were mistaken for interval counts.
How to fix it: Use appropriate increases with reset-aware semantics.
Prevent it next time: Document temporality and collection start times.

Latency appears one thousand times smaller

Why it happens: A unit conversion was not reflected in metadata or queries.
How to fix it: Align measurement, unit, and display conversion.
Prevent it next time: Test a known synthetic duration end to end.

A queue-depth counter never decreases

Why it happens: A current value was modeled as accumulating events.
How to fix it: Choose an instrument with matching up/down semantics.
Prevent it next time: Review quantity meaning before SDK implementation.

Check your understanding

1. A process reports cumulative values 80, 95, then 4 after restart. Is the last increase minus 91?

Show worked solution

No. The sequence crossed a reset, so ordinary subtraction across that boundary is invalid. Use the actual data model’s start-time or reset semantics and preserve uncertainty when observations are missing. The local no-reset fixture cannot establish the correct backend query for this case.

2. Should queue depth across three independent partitions be averaged or summed?