Instrumentation basics

This lesson builds a small dummy Flask application to demonstrate where and how to add Prometheus instrumentation. The focus is on adding metrics to capture HTTP activity, not on Flask itself. We’ll start with a minimal app, add a Prometheus counter, then show two ways to expose metrics: a separate metrics port and mounting metrics on the same Flask process.

Prerequisites

Python 3.x
pip
Flask
prometheus_client

Install Flask (if needed) and the Prometheus client:

pip install flask prometheus_client

1. Basic Flask app

A minimal API with one route. This is the starting point before adding instrumentation.

from flask import Flask, jsonify

app = Flask(__name__)

@app.get("/cars")
def list_cars():
    # Dummy response for the example
    return jsonify([{"id": 1, "make": "Toyota", "model": "Corolla"}])

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5001)

2. Install the Prometheus client for Python

Install the official Prometheus Python client (if you haven’t already):

pip install prometheus_client

3. Creating a simple counter metric

Define a Counter metric. Follow Prometheus naming conventions: lowercase, underscores, and a clear help string.

from prometheus_client import Counter, start_http_server

# Metric name should follow Prometheus naming conventions (lowercase, underscores)
http_requests_total = Counter("http_requests_total", "Total number of HTTP requests")

4. Instrumenting a route by incrementing the counter

Manually increment the counter inside the route handler:

@app.get("/cars")
def list_cars():
    http_requests_total.inc()  # increment by 1
    return jsonify([{"id": 1, "make": "Toyota", "model": "Corolla"}])

5. Expose metrics on a separate port using the built-in HTTP server

Use start_http_server(port) to expose metrics on a separate port (common pattern for simple setups). This serves metrics at the root path, e.g. http://127.0.0.1:8000/metrics.

if __name__ == "__main__":
    # start_http_server exposes metrics at the root path of the given port (e.g., http://127.0.0.1:8000)
    start_http_server(8000)
    app.run(host="0.0.0.0", port=5001)

Once running, you can fetch metrics with curl:

$ curl 127.0.0.1:8000/metrics

Example output (truncated):

# HELP python_gc_objects_uncollactable_total Uncollectable object found during GC
# TYPE python_gc_objects_uncollactable_total counter
python_gc_objects_uncollactable_total{generation="0"} 0.0
...
# HELP python_info Python platform information
# TYPE python_info gauge
python_info{implementation="CPython",major="3",minor="9",patchlevel="5",version="3.9.5"} 1.0
# HELP http_requests_total Total number of HTTP requests
# TYPE http_requests_total counter
http_requests_total 5.0

6. Exposing metrics via the Flask process (same port)

If you prefer metrics to be available on the same port as your Flask application, mount the Prometheus WSGI app at /metrics using DispatcherMiddleware:

from flask import Flask
from prometheus_client import make_wsgi_app
from werkzeug.middleware.dispatcher import DispatcherMiddleware

app = Flask(__name__)

# Mount the Prometheus WSGI app at /metrics so metrics are served by the Flask process
app.wsgi_app = DispatcherMiddleware(app.wsgi_app, {
    "/metrics": make_wsgi_app()
})

This makes metrics available at http://<host>:<flask_port>/metrics.

7. Adding more routes

As your API grows, you might add several endpoints. Here are examples that also increment the counter (manual increments shown):

from flask import request, jsonify

@app.get("/cars")
def list_cars():
    http_requests_total.inc()
    return jsonify([{"id": 1, "make": "Toyota", "model": "Corolla"}])

@app.get("/cars/<int:car_id>")
def get_car(car_id):
    http_requests_total.inc()
    return jsonify({"id": car_id, "make": "Toyota", "model": "Corolla"})

@app.post("/cars")
def create_car():
    http_requests_total.inc()
    # pretend to create a car
    return jsonify({"id": 2}), 201

@app.patch("/cars/<int:car_id>")
def update_car(car_id):
    http_requests_total.inc()
    # pretend to update a car
    return jsonify({"id": car_id})

@app.delete("/cars/<int:car_id>")
def delete_car(car_id):
    http_requests_total.inc()
    return "", 204

8. Making instrumentation less repetitive

Manually incrementing inside every handler works but is repetitive and error-prone. Use a centralized hook (middleware-style) to count requests once for all routes. Simple global counter increment with Flask’s before_request:

from flask import request

@app.before_request
def count_request():
    http_requests_total.inc()

Use labels to capture method and endpoint (be cautious with cardinality):

http_requests_total = Counter(
    "http_requests_total",
    "Total number of HTTP requests",
    ["method", "endpoint"]
)

@app.before_request
def count_request():
    # Use request.path or request.endpoint — request.path may increase cardinality
    http_requests_total.labels(method=request.method, endpoint=request.path).inc()

Use lowercase, underscore-separated names for Prometheus naming conventions. Be careful with label cardinality: using high-cardinality labels (such as full request paths with many unique IDs) can cause performance and storage problems. Prefer stable labels (method, named endpoint, status) over raw paths containing IDs. See Prometheus instrumentation best practices for more on labels and cardinality: https://prometheus.io/docs/practices/instrumentation/.

9. Which approach to choose?

start_http_server (separate port)
- Simple and language-agnostic for exposing metrics from a process.
- Works well when you can open a second port for scraping.
make_wsgi_app + DispatcherMiddleware (same port)
- Exposes /metrics on the same port as the Flask app.
- Useful in environments that restrict ports or when a single port is required.

Summary comparison:

Method	When to use	Example
`start_http_server` (separate port)	Simple deployments, language-agnostic scraping, or when you can allocate a metrics port	`start_http_server(8000)`
`make_wsgi_app` + `DispatcherMiddleware` (same port)	When you must serve metrics on the same port as the app (e.g., container port constraints)	`app.wsgi_app = DispatcherMiddleware(app.wsgi_app, {"/metrics": make_wsgi_app()})`

Either approach is valid — the key is placing instrumentation where it reliably captures the events you care about. For HTTP request counts, a centralized hook (middleware / before_request) is usually preferable to adding manual increments in each handler.

Introduction

Observability Fundamentals

Prometheus Fundamentals

PromQL

Dashboarding & Visualization

Application Instrumentation

Service Discovery

Push Gateway

Alerting

Monitoring Kubernetes

Conclusion

Scaling & Long Term Storage

Instrumentation basics

Prerequisites

1. Basic Flask app

2. Install the Prometheus client for Python

3. Creating a simple counter metric

4. Instrumenting a route by incrementing the counter

5. Expose metrics on a separate port using the built-in HTTP server

6. Exposing metrics via the Flask process (same port)

7. Adding more routes

8. Making instrumentation less repetitive

9. Which approach to choose?

References

Watch Video

​Prerequisites

​1. Basic Flask app

​2. Install the Prometheus client for Python

​3. Creating a simple counter metric

​4. Instrumenting a route by incrementing the counter

​5. Expose metrics on a separate port using the built-in HTTP server

​6. Exposing metrics via the Flask process (same port)

​7. Adding more routes

​8. Making instrumentation less repetitive

​9. Which approach to choose?

​References

Watch Video

Prerequisites

1. Basic Flask app

2. Install the Prometheus client for Python

3. Creating a simple counter metric

4. Instrumenting a route by incrementing the counter

5. Expose metrics on a separate port using the built-in HTTP server

6. Exposing metrics via the Flask process (same port)

7. Adding more routes

8. Making instrumentation less repetitive

9. Which approach to choose?

References