Understanding Prometheus Metric Types: Gauge, Counter, Summary, and Histogram Explained

Gauge

A gauge is the simplest metric type; it represents a value that can go up or down, such as current memory usage, queue length, or disk space. The Prometheus client provides methods to set an absolute value, increment, decrement, add, or subtract a delta.

// Set an absolute value
queueLength.Set(0)

// Increment by 1
queueLength.Inc()
// Decrement by 1
queueLength.Dec()
// Add a specific value
queueLength.Add(23)
// Subtract a specific value
queueLength.Sub(42)

When exported without additional labels, a gauge appears as a single time series in the text exposition format:

# HELP queue_length The number of items in the queue.
# TYPE queue_length gauge
queue_length 42

Because the current value of a gauge is meaningful, it is usually displayed directly in dashboards. In special cases, such as when the gauge records a timestamp, the displayed value may be transformed (e.g., current time minus the recorded timestamp).

Counter

A counter records a cumulative count that only increases over time, such as total HTTP requests handled or total processing time. It can only be reset to zero (e.g., when the process restarts). Counters provide two update methods: Inc() to add one and Add(x) to add an arbitrary value.

totalRequests.Inc()    // add 1
totalRequests.Add(23) // add 23

In the text exposition format, a counter looks similar to a gauge:

# HELP http_requests_total The total number of handled HTTP requests.
# TYPE http_requests_total counter
http_requests_total 7734

Since counters only increase, their absolute value is often less useful than the rate of change. Queries typically wrap counters with functions like rate(), irate(), or increase() to handle resets and compute per‑second or per‑interval rates.

Summary

A summary tracks observations (e.g., request durations) and calculates configurable quantiles. When creating a summary, you specify the desired quantiles and their tolerated error.

requestDurations := prometheus.NewSummary(prometheus.SummaryOpts {
    Name: "http_request_duration_seconds",
    Help: "A summary of the HTTP request durations in seconds.",
    Objectives: map[float64]float64 {
        // 0.5 quantile with 0.05 error
        0.5: 0.05,
        // 0.9 quantile with 0.01 error
        0.9: 0.01,
        // 0.99 quantile with 0.001 error
        0.99: 0.001,
    },
})

To record an observation, call Observe() with the measured value: requestDurations.Observe(2.3) The exported series includes one time series per configured quantile, plus total sum and count series:

# HELP http_request_duration_seconds A summary of the HTTP request durations in seconds.
# TYPE http_request_duration_seconds summary
http_request_duration_seconds{quantile="0.5"} 0.052
http_request_duration_seconds{quantile="0.90"} 0.564
http_request_duration_seconds{quantile="0.99"} 2.372
http_request_duration_seconds_sum 88364.234
http_request_duration_seconds_count 227420

In PromQL, you typically use the underlying counter and gauge components directly; summaries do not support aggregation across label dimensions.

Histogram

A histogram buckets observed values into configurable ranges, allowing approximate quantile calculations. Prometheus histograms are cumulative: each bucket includes counts of all lower buckets, so you only define the upper bound ( le) for each bucket.

requestDurations := prometheus.NewHistogram(prometheus.HistogramOpts{
    Name: "http_request_duration_seconds",
    Help: "A histogram of the HTTP request durations in seconds.",
    Buckets: []float64{0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10},
})

Observations are recorded with Observe(): requestDurations.Observe(2.3) The exported series includes a bucket time series for each upper bound, a total count, and a sum:

# HELP http_request_duration_seconds A histogram of the HTTP request durations in seconds.
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.05"} 4599
http_request_duration_seconds_bucket{le="0.1"} 24128
http_request_duration_seconds_bucket{le="0.25"} 45311
http_request_duration_seconds_bucket{le="0.5"} 59983
http_request_duration_seconds_bucket{le="1"} 60345
http_request_duration_seconds_bucket{le="2.5"} 114003
http_request_duration_seconds_bucket{le="5"} 201325
http_request_duration_seconds_bucket{le="+Inf"} 227420
http_request_duration_seconds_count 227420

The le label denotes the bucket's upper bound (e.g., le="2.5" counts requests ≤ 2.5 s). To estimate a quantile, use the histogram_quantile() function in PromQL:

histogram_quantile(0.9, rate(http_request_duration_seconds_bucket[5m]))

For recent‑window calculations, wrap the histogram with rate() or increase() to avoid using the entire lifetime data. Aggregation across dimensions (e.g., by path and method) can be performed with sum by(...) on the rate of bucket series.

Prometheus is testing a new metric type called Native Histogram , which will store the full histogram in a single time series; it is currently in the experimental stage.