Metric Types

A counter is a cumulative value that only ever increases, or resets to zero on restart — the number of requests served, tasks completed, or errors raised. Because a counter never decreases on its own, it’s rarely useful raw; wrap it in rate() or increase() to get a per-second or per-interval rate, which is what most counter-based charts and alerts actually plot.

Use a counter for anything that only accumulates. Don’t use one for a value that can go down on its own — the number of currently running processes, for example — that’s a gauge instead.

A gauge is a single numerical value that can move in either direction — temperature, memory usage, the number of active connections, or a count that goes up and down like concurrent requests. Unlike a counter, a gauge’s raw value is usually what you want to chart directly; aggregate it with avg, min, max, or sum rather than rate().

A histogram samples observed values — request durations, response sizes — into configurable buckets and also tracks their count and sum. It’s the most complex of the three types and the one to reach for whenever you need a distribution or a percentile rather than a single number, such as p95 latency.

Bucket boundaries are set by whoever instruments the metric, and querying a histogram means aggregating across its buckets — most commonly with histogram_quantile() to compute a percentile. See Miscellaneous functions for histogram_quantile() and the related histogram_avg(), histogram_stddev(), histogram_stdvar(), and histogram_fraction() functions.