HistogramSummary

In this lesson you’ll implement a Prometheus histogram to measure request latency (response time) per HTTP request using Flask and the Prometheus Python client. This approach captures the time from when a request arrives until the response is sent, records it in a histogram, and exposes metrics for Prometheus to scrape. Why this matters:

Track latency distributions, not just averages.
Compute quantiles using Prometheus (histogram_quantile()).
Aggregate latency across many instances with histogram buckets.

Links and references

Flask: https://flask.palletsprojects.com/en/latest/
Prometheus Python client: https://prometheus-client.readthedocs.io/en/latest/
histogram_quantile(): https://prometheus.io/docs/prometheus/latest/querying/functions/#histogram_quantile

Approach (step-by-step)

Create a histogram metric with the label names you need (for example, path and method).
Record a timestamp when the request starts (use @app.before_request).
Record another timestamp right before sending the response (use @app.after_request), subtract to get latency, then call .observe() on the histogram.

Example — full Flask application with a histogram:

# app.py
import time
from flask import Flask, request
from prometheus_client import start_http_server, Histogram

app = Flask(__name__)

# Make sure the labelnames order matches how you call `.labels(...)` below.
LATENCY = Histogram(
    'request_latency_seconds',
    'Flask Request Latency',
    labelnames=['path', 'method'],
)

@app.before_request
def before_request():
    # Store the start time on the Flask request object
    request.start_time = time.time()

@app.after_request
def after_request(response):
    # Calculate latency and record it in the histogram
    request_latency = time.time() - getattr(request, 'start_time', time.time())
    LATENCY.labels(request.path, request.method).observe(request_latency)
    return response

if __name__ == '__main__':
    # Expose Prometheus metrics on port 8000
    start_http_server(8000)
    # Run the Flask app
    app.run(host='0.0.0.0', port=5000)

Notes on Flask hooks

@app.before_request runs before each request handler and is the ideal place to capture the start timestamp.
@app.after_request runs when a view returns but before the response is sent. Use it to compute and record latency. Always return the response from after_request.

Important details and best practices

Keep label ordering consistent. The histogram is created with labelnames=['path', 'method']. When using positional labels, pass values in the same order: .labels(request.path, request.method). You can also use keyword labels: .labels(path=request.path, method=request.method).
Record metric values by calling .observe(value), where value is the measured latency in seconds (a float).
Expose metrics via the Prometheus client (here start_http_server(8000)), and configure Prometheus to scrape that endpoint.

When Prometheus scrapes /metrics the histogram exposes bucket counts, the total count, and the sum. Example scraped output:

# example scraped output (values for illustration)
request_latency_seconds_bucket{le="0.005",method="GET",path="/cars"} 0.0
request_latency_seconds_bucket{le="0.01",method="GET",path="/cars"} 0.0
request_latency_seconds_bucket{le="0.025",method="GET",path="/cars"} 0.0
request_latency_seconds_bucket{le="0.05",method="GET",path="/cars"} 1.0
request_latency_seconds_bucket{le="0.075",method="GET",path="/cars"} 3.0
request_latency_seconds_bucket{le="0.1",method="GET",path="/cars"} 3.0
request_latency_seconds_bucket{le="0.25",method="GET",path="/cars"} 4.0
request_latency_seconds_bucket{le="0.5",method="GET",path="/cars"} 6.0
request_latency_seconds_bucket{le="0.75",method="GET",path="/cars"} 6.0
request_latency_seconds_bucket{le="1.0",method="GET",path="/cars"} 8.0
request_latency_seconds_bucket{le="2.5",method="GET",path="/cars"} 8.0
request_latency_seconds_bucket{le="5.0",method="GET",path="/cars"} 8.0
request_latency_seconds_bucket{le="7.5",method="GET",path="/cars"} 8.0
request_latency_seconds_bucket{le="10.0",method="GET",path="/cars"} 8.0
request_latency_seconds_bucket{le="+Inf",method="GET",path="/cars"} 8.0
request_latency_seconds_count{method="GET",path="/cars"} 8.0
request_latency_seconds_sum{method="GET",path="/cars"} 1.234

Customizing buckets

Default buckets are useful for many web apps, but you may need different boundaries for your latency distribution. Supply a buckets= list when creating the Histogram:

LATENCY = Histogram(
    'request_latency_seconds',
    'Flask Request Latency',
    labelnames=['path', 'method'],
    buckets=[0.01, 0.02, 0.03, 0.04, 0.05, 0.06, 0.07, 0.08, 0.09, 0.1],
)

Choose bucket boundaries that reflect the performance characteristics you care about (e.g., sub-ms, ms, or seconds ranges).

Summary vs Histogram: when to use which

Histograms
- Allow you to configure buckets and compute quantiles across instances using Prometheus functions like histogram_quantile().
- Are usually the best choice when you need aggregated, cluster-wide quantiles.
Summaries
- Can provide client-side quantiles (e.g., 0.5, 0.9, 0.99) without bucket boundaries.
- Are limited because client-side quantiles do not aggregate well across instances.

Comparison table

Metric Type	Aggregation across instances	Configure buckets	Client-side quantiles	Typical use case
Histogram	Yes (via buckets + PromQL)	Yes	No	Aggregated latency distributions, cross-instance quantiles with `histogram_quantile()`
Summary	No (does not aggregate quantiles)	No	Yes (per-instance)	Per-instance quantiles when aggregation is not required

Example: switching to a Summary is as simple as replacing Histogram with Summary:

from prometheus_client import Summary

LATENCY = Summary(
    'request_latency_seconds',
    'Flask Request Latency',
    labelnames=['path', 'method'],
)

# record observations the same way:
# LATENCY.labels(request.path, request.method).observe(request_latency)

Histograms and summaries serve different use cases. Histograms are preferred when you need configurable buckets and aggregated quantiles via Prometheus’s histogram_quantile() function. Summaries provide client-side quantiles per instance but do not aggregate quantiles across multiple instances effectively.

A quick Python client note:

The Prometheus Python client has fewer features for Summary (for example, client-side quantile objectives) compared with some other language clients. If you require aggregated quantiles across multiple instances, prefer Histograms and calculate quantiles in Prometheus with histogram_quantile().

Introduction

Observability Fundamentals

Prometheus Fundamentals

PromQL

Dashboarding & Visualization

Application Instrumentation

Service Discovery

Push Gateway

Alerting

Monitoring Kubernetes

Conclusion

Scaling & Long Term Storage

Approach (step-by-step)

Customizing buckets

Summary vs Histogram: when to use which

Watch Video

​Approach (step-by-step)

​Customizing buckets

​Summary vs Histogram: when to use which

Watch Video

Approach (step-by-step)

Customizing buckets

Summary vs Histogram: when to use which