FastAPI Health Checks & Prometheus Metrics (Liveness, Readiness & Observability)

Prerequisites: a FastAPI app with a database (how-to-connect-fastapi-to-postgres). This is the metrics half of observability — pair it with structured logs from fastapi-logging.

fastapi-health-metrics/
├── requirements.txt
└── app/
    ├── __init__.py
    ├── database.py         # get_session
    ├── metrics.py          # custom Prometheus metrics
    └── main.py             # /health, /health/ready, /metrics

1The Problem: Flying Blind (See It First)

Ship a FastAPI app with no health endpoint and no metrics, and you've created two blind spots at once:

No health endpoint:
  Kubernetes/Docker: "is this container alive? ...I'll just assume yes."
  → a hung app keeps receiving traffic; a slow-starting app gets traffic
    before it's ready → users hit errors

No metrics:
  "Is the API slow right now? How many errors in the last 5 min?"
  → you have no idea until a user complains. You're debugging from logs
    alone, after the fact.

2Liveness vs Readiness (Don't Mix Them Up)

These are two different questions, and conflating them causes real outages. Liveness asks "is the process alive?" Readiness asks "can it serve traffic right now?"

3Liveness: A Dumb, Fast /health

Liveness should do nothing but confirm the app can respond. No DB, no external calls — just proof the event loop is running. Keep it trivial so it's fast and never falsely fails.

from fastapi import FastAPI

app = FastAPI(title="FastAPI Health & Metrics", version="0.1.0")


@app.get("/health", tags=["health"])
def liveness():
    # if this returns, the process is alive. That's the whole job.
    return {"status": "ok"}

4Readiness: Check Critical Dependencies

Readiness is where you verify the app can actually do its job — most importantly, that it can reach the database. If a dependency is down, return 503 so the orchestrator stops routing traffic until it recovers.

from typing import Annotated

from fastapi import Depends, HTTPException, status
from sqlalchemy import text
from sqlmodel import Session

from app.database import get_session

SessionDep = Annotated[Session, Depends(get_session)]


@app.get("/health/ready", tags=["health"])
def readiness(session: SessionDep):
    try:
        session.execute(text("SELECT 1"))          # can we reach the DB?
    except Exception:
        raise HTTPException(
            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
            detail="database unavailable",
        )
    return {"status": "ready"}

5Metrics 101: Measure the Right Things (RED)

Before adding metrics, know what matters. The RED method is the standard starting point for a request-driven service — three signals that tell you almost everything about its health:

6Exposing Prometheus Metrics

The prometheus-fastapi-instrumentator library gives you all the RED metrics — request count, status codes, and a latency histogram — and a /metrics endpoint in two lines. It hooks into the request cycle for you.

from prometheus_fastapi_instrumentator import Instrumentator

# after all routes are defined:
Instrumentator().instrument(app).expose(app)   # adds GET /metrics

Hit /metrics and you get the standard Prometheus exposition format:

$ curl -s http://127.0.0.1:8000/metrics | grep http_request

# HELP http_requests_total Total number of requests by method, status and handler.
http_requests_total{handler="/health",method="GET",status="2xx"} 42.0
http_requests_total{handler="/users",method="POST",status="2xx"} 7.0
# HELP http_request_duration_seconds Duration of HTTP requests in seconds.
http_request_duration_seconds_bucket{handler="/users",le="0.1"} 6.0
http_request_duration_seconds_bucket{handler="/users",le="0.5"} 7.0

7Custom Business Metrics

HTTP metrics tell you the API is healthy; business metrics tell you the product is. Add your own with prometheus-client (already installed as a dependency). A Counter for signups, a Gauge for something you can go up and down — they show up on the same /metrics.

from prometheus_client import Counter, Gauge

# name convention: app_<thing>_total for counters
signups_total = Counter(
    "app_signups_total",
    "Total number of successful signups",
)

active_websocket_connections = Gauge(
    "app_active_websocket_connections",
    "Currently open WebSocket connections",
)

from app.metrics import signups_total


@app.post("/signup", status_code=status.HTTP_201_CREATED)
def signup(session: SessionDep):
    # ...create the user...
    signups_total.inc()          # count a real business event
    return {"status": "created"}

$ curl -s http://127.0.0.1:8000/metrics | grep app_signups
# HELP app_signups_total Total number of successful signups
# TYPE app_signups_total counter
app_signups_total 3.0

8Try It

fastapi==0.116.1
uvicorn[standard]==0.30.6
sqlmodel==0.0.22
psycopg[binary]==3.2.1
prometheus-fastapi-instrumentator==7.0.0

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

# liveness — always fast, no deps
$ curl -s http://127.0.0.1:8000/health
{"status":"ok"}

# readiness — checks the DB
$ curl -s http://127.0.0.1:8000/health/ready
{"status":"ready"}

# stop Postgres, then readiness fails (liveness stays OK!)
$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/health/ready
503

# metrics
$ curl -s http://127.0.0.1:8000/metrics | head -n 5

9Common Mistakes (and Fixes)

10Production Notes

Wire the probes in Kubernetes so each does its job:

livenessProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 5
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8000
  initialDelaySeconds: 5
  periodSeconds: 5

And point Prometheus at the app:

scrape_configs:
  - job_name: fastapi
    metrics_path: /metrics
    static_configs:
      - targets: ["fastapi:8000"]

• Beware metric cardinality. Never put high-variety values (user id, order id, raw path) in labels — each combination is a new time series and will melt Prometheus. The instrumentator groups by route template (/users/{id}), not the actual id, on purpose.
• Protect /metrics. Keep it on an internal network or behind auth — it reveals traffic and error patterns you don't want public.
• Metrics + logs + traces. Metrics tell you something is wrong; structured logs (fastapi-logging) tell you what. Use them together.

11What's Next

Recap: give your app a dumb-and-fast /health for liveness and a dependency-checking /health/ready for readiness — never check the DB in liveness. Expose Prometheus /metrics for the RED signals, add custom counters for business events, and watch your cardinality. Now your orchestrator can heal the app, and you can actually see how it's doing.

fastapi-health-metrics/             # ✅ finished
├── requirements.txt                # + prometheus-fastapi-instrumentator
└── app/
    ├── database.py         # get_session
    ├── metrics.py          # custom Counter/Gauge
    └── main.py             # /health (liveness), /health/ready, /metrics