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

Metrics are numerical measurements that track performance, resource consumption, and efficiency over time, enabling engineers to monitor systems via alerts and dashboards. A basic metric data point consists of a name, a timestamp, and a numeric value. Modern systems add dimensions (labels) to provide context, allowing aggregation and filtering across components.

Prometheus defines a metric exposition format and a remote‑write protocol that have become de‑facto standards. OpenMetrics builds on the Prometheus format to create a vendor‑neutral model, while OpenTelemetry aims to unify metrics, traces, and logs under a single collection framework.

1. Prometheus Metric Types

Prometheus exposes four core metric types, each suited to different measurement patterns.

Counters

Counters only increase (or reset to zero on restart) and are ideal for tracking cumulative events such as total HTTP requests. They are typically suffixed with _total. Example PromQL queries:

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

Python client example:

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()

Gauges

Gauges represent values that can go up or down, such as temperature, CPU usage, or queue length. They are queried directly without rate or delta functions. Example PromQL functions for gauges include avg_over_time, max_over_time, min_over_time, and quantile_over_time.

Python client example:

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)

Histograms

Histograms record the distribution of observations by counting occurrences in predefined buckets. They expose three series: a counter for the total number of observations ( _count), a counter for the sum of observed values ( _sum), and a set of bucket counters ( _bucket with an le label).

Example exposition:

# 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 buckets) ...

Key PromQL queries:

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])

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

histogram_quantile(0.99, sum by (le) (rate(http_request_duration_seconds_bucket[5m])))

Python client example 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)

Summaries

Summaries also track count and sum but compute quantiles on the client side over a sliding time window. They expose _count, _sum, and optional quantile series. Summaries provide more precise quantile values but cannot be aggregated across instances.

Example exposition:

# 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 quantiles) ...

Python client example:

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)

Choosing Between Histograms and Summaries

Histograms are generally preferred because they allow aggregation and flexible quantile calculation via histogram_quantile. Summaries are useful when precise quantiles are required for a single instance and aggregation is not needed.

Both have trade‑offs: histograms need carefully designed bucket boundaries, and large numbers of buckets increase storage and computation costs; summaries incur client‑side memory overhead and cannot be aggregated across multiple instances.

2. Summary

The first part of this metrics series covered the four Prometheus metric types—Counters, Gauges, Histograms, and Summaries—explaining their data models, typical use‑cases, PromQL queries, and Python client implementations, as well as the advantages and limitations of each type.