Metric Instrument Types
Metric instruments — counter, gauge, histogram, and variants like exponential histograms — each answer different questions; choosing wrong turns valid data into misleading aggregates.
Definition
Instrument types define aggregation semantics. Counters only increase — rates, totals, cumulative events. Gauges go up and down — current state: queue depth, temperature, connections. Histograms (explicit or exponential bucket) capture distributions — latency, sizes — yielding percentiles via aggregation. Summaries compute quantiles client-side and cannot aggregate across instances.
Context and scope
The OpenTelemetry and Prometheus data model. Decided per metric at emission; wrong types surface as impossible queries and wrong dashboards months later.
Common misconceptions
- A gauge tracking request counts works — resetting or decreasing gauges cannot compute rates; counters exist precisely for rate queries
- Exponential histograms are a fancy optimization — they maintain resolution across wide dynamic ranges with fewer buckets; high-scale latency analysis benefits materially
- Summaries aggregate like histograms — client-side quantiles cannot be averaged across instances; histogram buckets merge correctly
Anti-patterns
- Recording latency as an average gauge and making percentile questions permanently unanswerable
- Using a gauge for cumulative events and computing negative rates on resets
- Choosing bucket layouts without seeing the data distribution and hiding the interesting range between buckets
Related concepts
Related examples
Authoritative source
What it is
The instrument type decides what questions the data can ever answer. A counter supports how-many-per-second forever. A gauge supports what-is-it-now. A histogram supports what-did-the-distribution-look-like. None can answer the others question.
How it works
Counters expose cumulative values; the backend differentiates over time windows. Gauges expose instantaneous values with no history guarantee. Histograms record observations into buckets with counts; backends merge buckets across instances and interpolate quantiles. Exponential histograms scale bucket boundaries geometrically, covering microsecond-to-hour ranges with fixed resource bounds.
When to choose
Events and throughput: counters. State sizes and saturation: gauges. Anything analyzed by percentile: histograms. Single-instance quantiles only: summaries — rarely the right call in fleets.
Pitfalls
Instrument mistakes are permanent for historical data: switching latency from average-gauge to histogram starts the histogram from zero history. Gauge resets (process restarts with non-cumulative export) look like negative events to rate math. Exponential histograms resolve low and high ranges elegantly but custom SLO thresholds may straddle buckets — verify bucket boundaries against alert thresholds.