healthkit 0.1.0

Professional health checks for FastAPI — DB, Redis, disk, memory in one endpoint

healthkit

Professional health checks for FastAPI -- DB, Redis, disk, memory in one endpoint.

Install

pip install healthkit

# With database drivers
pip install healthkit[postgres]
pip install healthkit[redis]
pip install healthkit[all]

Quick Start

One line to add production-grade health checks:

from fastapi import FastAPI
from healthkit import setup_health

app = FastAPI()

setup_health(
    app,
    postgres_url="postgresql://user:pass@localhost/mydb",
    redis_url="redis://localhost:6379/0",
)

That's it. Your app now has /health and /health/ready endpoints.

Endpoints

Endpoint	Purpose	Response
GET /health	Full health report	Overall status + details for each check
GET /health/ready	Readiness probe	Overall status only (for k8s)

Both return 200 when healthy and 503 when any check fails.

Example Response

{
  "status": "healthy",
  "checks": [
    {"name": "postgres", "status": "healthy", "latency_ms": 1.23},
    {"name": "redis", "status": "healthy", "latency_ms": 0.45},
    {"name": "disk", "status": "healthy", "usage_percent": 42.1, "free_gb": 58.32},
    {"name": "memory", "status": "healthy", "usage_percent": 61.3, "available_gb": 6.12}
  ]
}

Advanced Usage

For more control, use the HealthCheck class directly:

from fastapi import FastAPI
from healthkit import HealthCheck, check_postgres, check_disk, check_memory

app = FastAPI()

health = HealthCheck()
health.add(check_postgres, url="postgresql://user:pass@localhost/mydb")
health.add(check_disk, threshold_percent=85)
health.add(check_memory, threshold_percent=80)
health.mount(app)

Custom Checks

Add your own check functions -- sync or async:

async def check_external_api() -> dict:
    # your logic here
    return {"name": "external-api", "status": "healthy", "latency_ms": 52.1}

health.add(check_external_api)

Available Checks

Check	What it does	Extra dependency
check_postgres	Connects and runs SELECT 1	asyncpg
check_redis	Connects and sends PING	redis
check_disk	Reports usage %, fails if above threshold	--
check_memory	Reports usage %, fails if above threshold	--

Configuration

Parameter	Default	Description
postgres_url	--	PostgreSQL connection string
redis_url	--	Redis connection string
disk_threshold	90	Disk usage % to trigger unhealthy
memory_threshold	90	Memory usage % to trigger unhealthy

Kubernetes Integration

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

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

License

MIT