Understanding Prometheus Metric Types: Counters, Gauges, Histograms & Summaries

Metrics are used to measure performance, consumption, efficiency and many other software attributes over time, allowing engineers to monitor values such as CPU or memory usage, request latency, etc., via alerts and dashboards.

In its simplest form a metric data point consists of three parts: a metric name, a timestamp, and a numeric value.

Over the past decade, dimensional metrics have emerged, adding a set of labels (dimensions) to provide additional context, enabling aggregation and analysis across components.

Prometheus defines a metric exposition format and a remote write protocol, which have become de‑facto standards. OpenMetrics builds on the Prometheus format to provide a vendor‑neutral model, and OpenTelemetry aims to unify metrics, traces, and logs.

Prometheus Metric Types

Prometheus collects four metric types as part of its exposition format.

Counters

Gauges

Histograms

Summaries

Prometheus uses a pull model, scraping HTTP endpoints that expose metrics in either the Prometheus text format or the OpenMetrics format.

Counter

Counters are monotonically increasing values; they only go up, except when the process restarts and the counter resets to zero. They are typically used to count events such as API calls.

# HELP http_requests_total Total number of http api requests
# TYPE http_requests_total counter
http_requests_total{api="add_product"} 4633433

To calculate the per‑second rate you can use the PromQL

rate

function:

rate(http_requests_total{api="add_product"}[5m])

To compute the absolute increase over a period you can use

increase

:

increase(http_requests_total{api="add_product"}[5m])

Python example for creating a Counter:

from prometheus_client import Counter
api_requests_counter = Counter(
    'http_requests_total',
    'Total number of http api requests',
    ['api']
)
api_requests_counter.labels(api='add_product').inc()

Gauge

Gauges represent values that can go up or down, such as temperature, CPU usage, memory usage, or queue length.

# HELP node_memory_used_bytes Total memory used in the node in bytes
# TYPE node_memory_used_bytes gauge
node_memory_used_bytes{hostname="host1.domain.com"} 943348382

Typical PromQL functions for Gauges include

avg_over_time

,

max_over_time

,

min_over_time

, and

quantile_over_time

. Example to compute the average memory usage over the last 10 minutes:

avg_over_time(node_memory_used_bytes{hostname="host1.domain.com"}[10m])

Python example for creating a Gauge:

from prometheus_client import Gauge
memory_used = Gauge(
    'node_memory_used_bytes',
    'Total memory used in the node in bytes',
    ['hostname']
)
memory_used.labels(hostname='host1.domain.com').set(943348382)

Histogram

Histograms are useful for observing the distribution of measurements, such as request durations. They consist of a count Counter, a sum Counter, and a series of bucket Counters with the

le

label.

# HELP http_request_duration_seconds Api requests response time in seconds
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_sum{api="add_product",instance="host1.domain.com"} 8953.332
http_request_duration_seconds_count{api="add_product",instance="host1.domain.com"} 27892
http_request_duration_seconds_bucket{api="add_product",instance="host1.domain.com",le="0.01"} 0
... (additional bucket lines) ...
http_request_duration_seconds_bucket{api="add_product",instance="host1.domain.com",le="+Inf"} 27892

Average request duration over the last 5 minutes:

rate(http_request_duration_seconds_sum{api="add_product",instance="host1.domain.com"}[5m]) / rate(http_request_duration_seconds_count{api="add_product",instance="host1.domain.com"}[5m])

99th percentile using

histogram_quantile

:

histogram_quantile(0.99, rate(http_request_duration_seconds_bucket{api="add_product",instance="host1.domain.com"}[5m]))

Python example for a Histogram with custom buckets:

from prometheus_client import Histogram
api_request_duration = Histogram(
    name='http_request_duration_seconds',
    documentation='Api requests response time in seconds',
    labelnames=['api', 'instance'],
    buckets=(0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 25)
)
api_request_duration.labels(api='add_product', instance='host1.domain.com').observe(0.3672)

Summary

Summaries also measure request duration and size, providing total count, sum, and configurable quantiles calculated on the client side.

# HELP http_request_duration_seconds Api requests response time in seconds
# TYPE http_request_duration_seconds summary
http_request_duration_seconds_sum{api="add_product",instance="host1.domain.com"} 8953.332
http_request_duration_seconds_count{api="add_product",instance="host1.domain.com"} 27892
http_request_duration_seconds{api="add_product",instance="host1.domain.com",quantile="0.5"} 0.232227334
... (additional quantile lines) ...

Python example for a Summary (note: the Python client does not support quantile calculation):

from prometheus_client import Summary
api_request_duration = Summary(
    'http_request_duration_seconds',
    'Api requests response time in seconds',
    ['api', 'instance']
)
api_request_duration.labels(api='add_product', instance='host1.domain.com').observe(0.3672)

Histogram vs Summary

In most cases Histograms are preferred because they are more flexible and allow aggregation of percentiles. Summaries are useful when precise quantiles are required and aggregation is not needed.