Skip to content

Setup

To set up a FastAPI app with Prometheus for metrics and Grafana for visualization

pipenv install fastapi uvicorn prometheus-fastapi-instrumentator

# or

pipenv install fastapi uvicorn prometheus_client

For development (auto-reload, etc.):

pipenv install --dev python-dotenv

The difference between prometheus_client and prometheus-fastapi-instrumentator lies in abstraction level, ease of use, and target use-case:

🔧 prometheus_client

What it is:

  • The official low-level Python client for Prometheus.
  • Lets you define and manage metrics manually (counters, histograms, gauges, etc.).
  • Framework-agnostic (can be used with FastAPI, Flask, Django, etc.).

Use it when:

  • You want fine-grained control over metrics.
  • You're building custom instrumentation.
  • You're not using FastAPI or need something portable.
  • You are okay with writing more boilerplate (e.g., creating endpoints, tracking latencies manually).

Pros:

  • Full control.
  • Official and well-maintained.
  • No external abstraction.

Cons:

  • More boilerplate.
  • Not plug-and-play with FastAPI.

🚀 prometheus-fastapi-instrumentator

What it is:

  • A high-level wrapper around prometheus_client for FastAPI applications.
  • Automatically instruments common metrics like HTTP request durations, status codes, path info, etc.
  • Adds a ready-made /metrics endpoint.
  • Allows customization, but handles most Prometheus boilerplate for you.

Use it when:

  • You're using FastAPI.
  • You want easy and fast instrumentation.
  • You're okay with some abstraction.
  • You want to avoid manual metric wiring for HTTP metrics.

Pros:

  • Plug-and-play.
  • Auto-instruments your app.
  • Saves time for typical web metrics.

Cons:

  • Slightly less control than prometheus_client.
  • Adds an extra dependency.
  • Not suited for non-FastAPI apps.

✅ Which One Should You Use?

Use Case Recommendation
You're using FastAPI and want easy metrics (request count, latency, etc.) ✅ Use prometheus-fastapi-instrumentator
You're building a custom metrics system or working outside FastAPI ✅ Use prometheus_client
You need both: automatic HTTP metrics and some custom metrics Use both together (the instrumentator internally uses prometheus_client)

Example:

prometheus-fastapi-instrumentator:

from fastapi import FastAPI
from prometheus_fastapi_instrumentator import Instrumentator

app = FastAPI()
Instrumentator().instrument(app).expose(app)

@app.get("/")
def read_root():
    return {"Hello": "World"}

prometheus_client (manual):

from fastapi import FastAPI, Request
from prometheus_client import Counter, generate_latest
from starlette.responses import Response

app = FastAPI()
REQUEST_COUNT = Counter("request_count", "Total number of requests")

@app.middleware("http")
async def count_requests(request: Request, call_next):
    REQUEST_COUNT.inc()
    return await call_next(request)

@app.get("/metrics")
def metrics():
    return Response(generate_latest(), media_type="text/plain")

If you're prototyping, building APIs quickly, or don’t need full control: start with prometheus-fastapi-instrumentator. You can always drop down to prometheus_client if needed.