I built fastapi-watch because FastAPI doesn't ship with any real observability out of the box. If you want to know what's actually happening inside your app — whether your database is healthy, how your queues are behaving, what your error rates look like — you're either writing it yourself or paying for something like NewRelic or Datadog. I wanted something in-depth that gave me the full picture without the cost or complexity. The goal was to keep it as lightweight, simple to set up, and non-interfering as possible.

The typical /health endpoint that just returns {"status": "ok"} telling you absolutely nothing. Writing per-app health logic from scratch means handling concurrency, caching, circuit breaking, Prometheus metrics, and SSE streaming yourself — every time.

What it does

Add /health/live, /health/ready, /health/status, /health/history, /health/metrics, and /health/dashboard to any FastAPI app with a single registry call:

from fastapi import FastAPI
from fastapi_watch import HealthRegistry
from fastapi_watch.probes import PostgreSQLProbe, RedisProbe

app = FastAPI()

registry = HealthRegistry(app, grace_period_ms=10_000)
registry.add(PostgreSQLProbe(url="postgresql://user:pass@localhost/mydb"))
registry.add(RedisProbe(url="redis://localhost:6379"), critical=False)

All probes run concurrently, so if, for example, Redis takes 5 seconds to respond, your Postgres check still comes back in 2ms and your /health/ready endpoint doesn't stall waiting for it. Each probe lives in its own async task and reports independently.

A few things I think are worth highlighting

Passive observers instead of synthetic pings. Many of the built-in probes (PostgreSQL, Redis, MongoDB, HTTP, SMTP) use a @probe.watch decorator to instrument your existing functions rather than making their own test requests on a timer. This means no extra load on your dependencies and no burned API credits on third-party services.

pg_probe = PostgreSQLProbe(name="primary-db", max_error_rate=0.01)

@pg_probe.watch
async def get_user(user_id: int):
    async with pool.acquire() as conn:
        return await conn.fetchrow("SELECT * FROM users WHERE id = $1", user_id)

registry.add(pg_probe)

Three-state health. Probes can return healthy, degraded, or unhealthy. Degraded means "still serving traffic but investigate soon" — /health/ready stays 200, the dashboard shows amber, and Prometheus surfaces a probe_degraded gauge.

ProbeGroup mirrors FastAPI's APIRouter pattern so you can declare probes in the modules that own them and include them at startup — same pattern you already use for routes.

Live dashboard at /health/dashboard — self-contained HTML, no extra dependencies, updates in real time over SSE.

Kubernetes

Maps directly onto Kubernetes probe types:

livenessProbe:
  httpGet:
    path: /health/live
    port: 8000

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8000

startupProbe:
  httpGet:
    path: /health/startup
    port: 8000
  failureThreshold: 30
  periodSeconds: 5

Built-in probes

PostgreSQL, MySQL, SQLAlchemy, Redis, Memcached, RabbitMQ, Kafka, MongoDB, Celery, HTTP, SMTP, TCP/DNS, EventLoop lag, and more — each returning service-specific metadata in the details field alongside the pass/fail result.

Alerting

You can hook into state changes to fire alerts whenever a probe flips between healthy, degraded, and unhealthy. There are built-in alerters for Slack, Microsoft Teams, and PagerDuty, or you can pass any HTTP endpoint as a generic webhook. Custom alerters are also supported if you need something more specific — just subclass BaseAlerter and implement a single notify method.

from fastapi_watch.alerts import SlackAlerter, PagerDutyAlerter

registry = HealthRegistry(
    app,
    alerters=[
        SlackAlerter(webhook_url="https://hooks.slack.com/...", channel="#ops-alerts"),
        PagerDutyAlerter(routing_key="your-routing-key"),
    ],
)

Alerts are fire-and-forget and never block health check execution. They're also automatically suppressed during maintenance mode, so you don't get paged for planned downtime.

Links

• GitHub: https://github.com/rgreen1207/fastapi-watch
• PyPI: https://pypi.org/project/fastapi-watch/
• Install: pip install fastapi-watch

Would love feedback — especially from anyone running FastAPI in Kubernetes or behind a load balancer. Happy to answer questions or take feature requests.