Skip to main content

fastapi-watch

Structured health and readiness checks for FastAPI.

Test, Build & Publish PyPI version Supported Python versions PyPI Downloads


Add /health/* endpoints to any FastAPI app in minutes. Probes observe real traffic — no synthetic requests — and stream live results to a built-in dashboard and Prometheus endpoint.

For full documentation see DOCS.md.


Installation

pip install fastapi-watch

# With service-specific extras
pip install "fastapi-watch[postgres,redis]"
pip install "fastapi-watch[all]"

zsh users: quote extras to avoid glob expansion: pip install "fastapi-watch[redis]"

Available extras: postgres, mysql, sqlalchemy, redis, memcached, rabbitmq, kafka, mongo, celery


Quick start

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

@asynccontextmanager
async def lifespan(app):
    # Automatically monitor every route — no decorators needed
    registry.discover_routes(tags=["api"], max_error_rate=0.05)
    registry.set_started()
    yield

# Create the app first: the registry mounts its routes on this instance.
app = FastAPI(lifespan=lifespan)
registry = HealthRegistry(app)

# Infrastructure probes observe your real calls: decorate them with @probe.watch
db_probe = PostgreSQLProbe(name="postgres")
cache_probe = RedisProbe(name="redis")
registry.add(db_probe)
registry.add(cache_probe, critical=False)

@db_probe.watch
async def fetch_user(user_id: int):
    return await pool.fetchrow("SELECT * FROM users WHERE id = $1", user_id)

Every route is now monitored with real-traffic data. Health endpoints are live at /health/*.


Endpoints

Endpoint Purpose Status
GET /health/live Liveness — process is alive 200 while the process runs (401/403 without credentials when auth= is set)
GET /health/ready Readiness — all critical probes passing 200 / 503 / 404 for a ?probe=/?tag= that selects nothing
GET /health/status Full probe detail 200 / 207 / 404 as above
GET /health/dashboard Live HTML dashboard (SSE) 200
GET /health/dashboard/stream-url Fresh dashboard stream URL and token — built-in dashboard with auth= only 200
GET /health/metrics Prometheus text format 0.0.4 200
GET /health/history Rolling result history per probe 200 / 503 when storage fails
GET /health/alerts Probe state-change log 200 / 503 when storage fails
GET /health/startup Startup gate; 503 until set_started() 200 / 503
GET /health/ready/stream SSE stream of readiness stream / 404 as above
GET /health/status/stream SSE stream of full probe detail (?view=dashboard trims per-route data to what the dashboard charts) stream / 404 as above
GET /health/maintenance Maintenance mode status 200
POST /health/maintenance Enable maintenance mode — mounted only when auth= is set 200 / 413 / 415 / 422
DELETE /health/maintenance Disable maintenance mode — mounted only when auth= is set 200
GET /health/probes Registered probe config (no probe runs) 200

The prefix defaults to /health and is configurable: HealthRegistry(app, prefix="/ops/health").


Route monitoring

The fastest way to monitor your API is auto-discovery. fastapi-watch monitors real traffic — no synthetic polling, no wasted requests.

discover_routes — monitor everything at once

One call after all routers are included. Every route gets a passive probe with no decorators required.

@asynccontextmanager
async def lifespan(app):
    registry.discover_routes(
        tags=["api"],              # tag all probes for filtering
        max_error_rate=0.05,       # alert if error rate exceeds 5%
        include_paths=["/api/*"],  # whitelist — only monitor these routes
        exclude_paths=["/api/admin"],  # exclude even if include_paths matches
    )
    registry.set_started()
    yield

Auto-discovered probes use GET /items/{id} style descriptions so they're immediately recognizable in the dashboard.

watch_router — monitor a specific router

Scope monitoring to one router with its own tags, thresholds, and criticality. Call it after app.include_router.

app.include_router(users_router, prefix="/users")
app.include_router(orders_router, prefix="/orders")

registry.watch_router(users_router, tags=["users"], max_error_rate=0.01)
registry.watch_router(orders_router, tags=["orders"], critical=False)

Then filter health checks by router: GET /health/ready?tag=users

@probe.watch — full control on one route

For routes that need custom thresholds, a specific name, or tight SLOs.

from fastapi_watch import FastAPIRouteProbe

checkout_probe = FastAPIRouteProbe(
    name="checkout",
    description="Payment processing",
    tags=["payments"],
    max_error_rate=0.001,
    slow_call_threshold_ms=200,
)

@app.post("/checkout")
@checkout_probe.watch
async def checkout():
    ...

registry.add(checkout_probe)

Priority system

When all three approaches are used together, each route is monitored exactly once — the highest-priority wins:

Priority Method When to use
1 — highest @probe.watch One route needs its own thresholds or name
2 watch_router A whole router shares settings
3 — lowest discover_routes Catch-all for everything not handled explicitly

discover_routes and watch_router skip any route already covered by a higher-priority method — no conflicts, no double counting.


Tag-based filtering

All probes accept tags=[...]. FastAPI route tags (@app.get("/items", tags=["store"])) are automatically merged in. Filter any endpoint by tag:

GET /health/ready?tag=payments         # only payment probes
GET /health/status?tag=users,orders    # users OR orders probes
GET /health/status/stream?tag=payments # filtered live stream

Filter by exact probe name with ?probe= (comma-separated, AND'd with ?tag= when both are given):

GET /health/status?probe=postgresql,redis   # only these two probes
GET /health/status?tag=payments&probe=checkout  # must match both

A filter naming an unregistered probe or tag (a typo such as ?probe=postgress), even alongside names that match, gets 404 with the unknown names, never a passing report, and the dashboard lists the name under "Requested but not registered". Known filters that together select nothing also get 404 ("no probe matches every filter").

The dashboard shows tag chips on each probe card and a clickable filter bar to isolate groups at a glance.


Infrastructure probes

from fastapi_watch.probes import PostgreSQLProbe, RedisProbe, HttpProbe, TCPProbe

registry.add(PostgreSQLProbe(name="postgres"))
registry.add(RedisProbe(name="redis"), critical=False)
registry.add(HttpProbe(name="payments-api"), critical=True)
registry.add(TCPProbe(host="kafka.internal", port=9092))

Passive probes observe real calls — use @probe.watch on any function to track its latency, error rate, and throughput without making synthetic requests.


Alerting

from fastapi_watch.alerts import SlackAlerter, PagerDutyAlerter, OpsGenieAlerter

registry = HealthRegistry(
    app,
    alerters=[
        SlackAlerter(webhook_url="https://hooks.slack.com/..."),
        PagerDutyAlerter(routing_key="your-routing-key"),
        OpsGenieAlerter(api_key="your-api-key"),
    ],
)

Webhook URLs are validated at construction time — private/loopback/link-local IP targets are rejected to prevent SSRF.


Custom storage backend

Results, history, and alerts live in process memory by default. To share them across workers or keep them across restarts, use the bundled Redis backend (pip install "fastapi-watch[redis]"):

import redis.asyncio as redis
from fastapi_watch import HealthRegistry, RedisProbeStorage

client = redis.from_url("redis://localhost:6379/0")  # decode_responses=True also works

registry = HealthRegistry(
    app,
    storage=RedisProbeStorage(client, prefix="myapp:health", max_entry_bytes=8192),
    history_size=120,            # entries kept per probe
    result_ttl_seconds=7200,     # per-entry age limit (0 = no age limit)
    max_alerts=120,
    alert_ttl_seconds=259200,
)

The four retention arguments are passed to HealthRegistry here, so the registry applies them to the backend through configure(). Leave all four out and the backend keeps its own constructor values (RedisProbeStorage(..., max_results=..., result_ttl_seconds=..., alert_ttl_seconds=..., max_alerts=...), same defaults).

It is safe to point at the Redis your app already uses: it never runs KEYS or SCAN, every write is a single MULTI/EXEC round trip, and all keys sit under prefix. Cleanup of removed probes (forget()) only deletes names the same process wrote and no longer registers, so apps and replicas sharing a prefix never delete each other's data, even during a rolling deploy. History, alerts and the dashboard show only the app's own probes, so apps sharing a prefix do not see each other's data. Still, give each app its own prefix: two apps that register the same probe name on one prefix share that probe's data. Storage is capped by count, by age (per entry), and by bytes:

redis bytes ≤ probes × ((history_size + 1) × max_entry_bytes + probe name) + max_alerts × (~150 B + probe name)

Replicas sharing a prefix also share alert dedupe: claim_alert(key, value, ttl_seconds) is one atomic compare-and-set (a short Lua script), so only one replica sends each alert, a status the probe returns to within the window is sent again, and every claim key expires.

Latest results and history entries larger than max_entry_bytes drop their largest details values first and are marked details["_truncated"] = true. With the defaults, 20 probes take at most about 19 MB of history, and typically far less. The backend runs at most max_connections (default 4) Redis commands at once, so checking many probes together cannot drain a connection pool your app shares.

To write your own backend (PostgreSQL, Memcached, ...), implement the ProbeStorage protocol. See DOCS.md — Custom storage backends.


Security

Health endpoints are publicly accessible by default — set auth in production:

registry = HealthRegistry(app, auth={"type": "basic", "username": "ops", "password": "secret"})

To manually reset a circuit breaker (e.g. after you've fixed the underlying issue and don't want to wait for the cooldown):

registry.reset_circuit("postgresql")  # clears open state and failure count; returns self

To skip all route registration entirely and expose health status on your own endpoint with custom auth:

registry = HealthRegistry(app, serve_routes=False)

@app.get("/internal/health", dependencies=[Depends(my_auth)])
async def my_health():
    report = await registry.get_report()
    return report.model_dump()

See DOCS.md — Security for auth callables, SSRF protection on webhook alerters, probe error message handling, and probe name restrictions.


License

MIT


Claude used to write README, code annotation, help with test case coverage, and clean up my messy thoughts into readable code.

Metadata

Release files for fastapi-watch 1.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fastapi-watch 1.8.0
File Size Uploaded Provenance Actions
fastapi_watch-1.8.0.tar.gz 322.0 kB With provenance Details for fastapi_watch-1.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fastapi-watch 1.8.0
File Interpreter ABI Platform Actions
fastapi_watch-1.8.0-py3-none-any.whl Python 3 none any Details for fastapi_watch-1.8.0-py3-none-any.whl

Total release size: 470.2 kB

Release files / fastapi_watch-1.8.0.tar.gz

Download URL fastapi_watch-1.8.0.tar.gz
Size 322.0 kB
Tags Source
SHA-256 checksum
How to use checksums
5e57880dfe9909c0c2ca5706f271250cdc73a8779522f40d8f3704b6a6fd1dcb
BLAKE2b-256 checksum
How to use checksums
ee2f1cd344c1d310e3c9bb239f568d5cd46944d4d90883ef6a14536292fabbc0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.

Transparency log

Release files / fastapi_watch-1.8.0-py3-none-any.whl

Download URL fastapi_watch-1.8.0-py3-none-any.whl
Size 148.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1ad12802d1c0189e07f1141de3b876a98e13bcf5e2840aca6cfccfc4f3704b07
BLAKE2b-256 checksum
How to use checksums
98c56db3b3339ad2e0f0b3e14d5b3d2b396cd6a8aaf9edbacf5eee31494615fe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.

Transparency log

Security for fastapi-watch 1.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for fastapi_watch-1.8.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.8.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page