Labels

Let’s extend our application so it exposes separate endpoints for cars and boats. We still want a single metric that tracks total HTTP requests, but we also want to break it down by endpoint (path) and optionally by HTTP method. Below are recommended patterns to track requests with the Python Prometheus client, including examples, PromQL queries, and guidance on label usage.

Use labels when you need flexible, multi-dimensional metrics (for example, to filter or aggregate by endpoint and method). Labels keep metric names stable and make aggregation easier.

1) Single global counter (simple)

A basic approach increments the same counter for every endpoint. This gives you the global total but no breakdown by path.

from prometheus_client import Counter

REQUESTS = Counter(
    'http_requests_total',
    'Total number of requests'
)

@app.get("/cars")
def get_cars():
    REQUESTS.inc()
    return ["toyota", "honda", "mazda", "lexus"]

@app.post("/cars")
def create_cars():
    REQUESTS.inc()
    return "Create Car"

@app.get("/boats")
def get_boats():
    REQUESTS.inc()
    return ["boat1", "boat2", "boat3"]

@app.post("/boats")
def create_boat():
    REQUESTS.inc()
    return "Create Boat"

Pros:

Very simple to implement. Cons:
No visibility into which endpoint handled the requests.

2) Separate counters per endpoint (scales poorly)

You can create a separate Counter for each path. This works but becomes brittle and hard to maintain as endpoints grow.

car_requests = Counter('car_requests_total', 'Total requests to /cars')
boat_requests = Counter('boat_requests_total', 'Total requests to /boats')

@app.get("/cars")
def get_cars():
    car_requests.inc()
    return ["toyota", "honda", "mazda", "lexus"]

@app.post("/cars")
def create_cars():
    car_requests.inc()
    return "Create Car"

@app.get("/boats")
def get_boats():
    boat_requests.inc()
    return ["boat1", "boat2", "boat3"]

@app.post("/boats")
def create_boat():
    boat_requests.inc()
    return "Create Boat"

Drawbacks:

You lose a single metric name for aggregation unless you sum across many metric names.
Adding endpoints requires creating and managing more metrics and updating dashboards/queries.

3) Recommended: a single Counter with labels

Use a single Counter and declare label names to create dimensions (for example path, and optionally method). Then increment the specific time series using labels(...):

from prometheus_client import Counter

REQUESTS = Counter(
    'http_requests_total',
    'Total number of requests',
    labelnames=['path']
)

@app.get("/cars")
def get_cars():
    REQUESTS.labels('/cars').inc()
    return ["toyota", "honda", "mazda", "lexus"]

@app.post("/cars")
def create_cars():
    REQUESTS.labels('/cars').inc()
    return "Create Car"

@app.get("/boats")
def get_boats():
    REQUESTS.labels('/boats').inc()
    return ["boat1", "boat2", "boat3"]

@app.post("/boats")
def create_boat():
    REQUESTS.labels('/boats').inc()
    return "Create Boat"

This yields multiple time series under the metric name http_requests_total, each differentiated by the path label. It keeps metric names stable and makes aggregation straightforward.

Example PromQL queries and exposition output

$ http_requests_total{path="/cars"}
http_requests_total{path="/cars"} 5.0

$ http_requests_total{path="/boats"}
http_requests_total{path="/boats"} 2.0

$ http_requests_total
http_requests_total{path="/cars"} 5.0
http_requests_total{path="/boats"} 2.0

$ sum(http_requests_total)
{} 7.0

Using multiple labels (path + method)

Add other dimensions by declaring more label names and passing values to labels() in the same order:

from prometheus_client import Counter

REQUESTS = Counter(
    'http_requests_total',
    'Total number of requests',
    labelnames=['path', 'method']
)

@app.get("/cars")
def get_cars():
    REQUESTS.labels('/cars', 'GET').inc()
    return ["toyota", "honda", "mazda", "lexus"]

@app.post("/cars")
def create_cars():
    REQUESTS.labels('/cars', 'POST').inc()
    return "Create Car"

@app.get("/boats")
def get_boats():
    REQUESTS.labels('/boats', 'GET').inc()
    return ["boat1", "boat2"]

@app.post("/boats")
def create_boat():
    REQUESTS.labels('/boats', 'POST').inc()
    return "Create Boat"

Now http_requests_total contains separate time series for each combination of path and method. Example queries:

All series for the metric:

$ http_requests_total
http_requests_total{path="/cars",method="GET"} 3.0
http_requests_total{path="/cars",method="POST"} 2.0
http_requests_total{path="/boats",method="GET"} 2.0
http_requests_total{path="/boats",method="POST"} 0.0

Filter by HTTP method:

$ http_requests_total{method="GET"}
http_requests_total{path="/cars",method="GET"} 3.0
http_requests_total{path="/boats",method="GET"} 2.0

Filter by path and aggregate methods for that path:

$ http_requests_total{path="/cars"}
http_requests_total{path="/cars",method="GET"} 3.0
http_requests_total{path="/cars",method="POST"} 2.0

$ sum(http_requests_total{path="/cars"})
{} 5.0

Be careful about high-cardinality label values (for example, user IDs, request IDs, or arbitrary URLs). Each unique label combination creates a new time series, which can consume a lot of memory and cause performance issues. Only use labels for dimensions you need to aggregate or filter on.

Quick comparison

Approach	Pros	Cons	When to use
Single global counter	Very simple	No per-endpoint visibility	Small apps, coarse telemetry
Separate counters per endpoint	Explicit per-endpoint metrics	Hard to manage, hard to aggregate	Very small number of endpoints and stable surface area
Single counter with labels	Flexible, easy aggregation (e.g. `sum(...)`)	Risk of high cardinality if misused	Recommended for most services needing per-path/method breakdowns

Introduction

Observability Fundamentals

Prometheus Fundamentals

PromQL

Dashboarding & Visualization

Application Instrumentation

Service Discovery

Push Gateway

Alerting

Monitoring Kubernetes

Conclusion

Scaling & Long Term Storage

1) Single global counter (simple)

2) Separate counters per endpoint (scales poorly)

3) Recommended: a single Counter with labels

Example PromQL queries and exposition output

Using multiple labels (path + method)

Quick comparison

Links and references

Watch Video

​1) Single global counter (simple)

​2) Separate counters per endpoint (scales poorly)

​3) Recommended: a single Counter with labels

​Example PromQL queries and exposition output

​Using multiple labels (path + method)

​Quick comparison

​Links and references

Watch Video

1) Single global counter (simple)

2) Separate counters per endpoint (scales poorly)

3) Recommended: a single Counter with labels

Example PromQL queries and exposition output

Using multiple labels (path + method)

Quick comparison

Links and references