Python Prometheus Client Supported Metric Types

Monitoring Python applications with Prometheus requires tracking performance data using specific data structures designed for time-series analysis. The official prometheus_client Python library provides four core metric types defined by the Prometheus specification—Counter, Gauge, Summary, and Histogram—along with specialized utilities like Info and Enum. This guide outlines how each metric type works, their specific behavioral rules, and typical use cases in application instrumentation.

Counter

A Counter is a cumulative metric that represents a single monotonically increasing value. Its value can only increase or be reset to zero upon application restart.

• Best Used For: Tracking the number of requests served, tasks completed, or errors encountered.
• Key Methods: inc(amount=1) increases the counter.
• Usage Note: Do not use a Counter for values that can decrease, such as currently running processes or memory usage.

Gauge

A Gauge represents a single numerical value that can arbitrarily go up and down. It reflects a snapshot of the current state of a particular component.

• Best Used For: Measuring resource utilization (CPU, memory, disk usage), current concurrent connections, temperature, or queue sizes.
• Key Methods: set(value), inc(amount=1), dec(amount=1), and set_to_current_time().
• Usage Note: Gauges can also be used as context managers or decorators via track_inprogress() to automatically monitor concurrent task execution.

Histogram

A Histogram samples observations (usually request durations or response sizes) and counts them into configurable, cumulative buckets. It also provides a sum of all observed values and a count of events.

• Best Used For: Measuring latency, request duration, and payload sizes where calculating percentiles (like 95th or 99th percentiles) across multiple application instances is required using Prometheus's histogram_quantile() PromQL function.
• Key Methods: observe(amount), time() (as a decorator or context manager).
• Usage Note: Histograms are aggregated on the Prometheus server, making them cost-effective and accurate across distributed systems compared to pre-computed percentiles.

Summary

A Summary samples observations and, like a Histogram, provides total counts and sums. Additionally, it calculates configurable quantiles over a sliding time window directly on the client side.

• Best Used For: Measuring request durations and payload sizes when you need precise quantiles directly from the client without configuring histogram buckets.
• Key Methods: observe(amount), time() (as a decorator or context manager).
• Usage Note: Summaries cannot be aggregated across multiple application instances on the Prometheus server. They also carry a higher client-side memory and CPU footprint than Histograms.

Info

The Info metric is an extended type used to expose key-value label data that remains static or changes infrequently during runtime.

• Best Used For: Exposing application metadata, such as software versions, compiler versions, or git commit hashes.
• Key Methods: info({'version': '1.2.0', 'build': 'production'}).

Enum

The Enum metric tracks states from a predefined set of distinct values. It exposes a single gauge metric where the active state has a value of 1 and all other states have a value of 0.

• Best Used For: Monitoring state machine statuses, system health flags, or readiness checks (e.g., starting, ready, stopping).
• Key Methods: state(state_name).