fastuator 0.1.0

Production-ready actuator endpoints for FastAPI (health, metrics, info)

Fastuator

Production-ready monitoring toolkit for FastAPI applications.
Kubernetes probes, Prometheus metrics, and health checks in one line.

✨ Features

• 🏥 Health Checks: Aggregated health status with customizable checks
• 🔍 K8s Probes: Built-in liveness and readiness endpoints
• 📊 Prometheus Metrics: Auto-instrumented HTTP metrics
• ℹ️ System Info: Build version and platform details
• 🎯 Zero Config: Works out of the box with sensible defaults
• ⚡ 100% Test Coverage: Battle-tested and production-ready

📦 Installation

pip install fastuator

🚀 Quick Start

from fastapi import FastAPI
from fastuator import Fastuator

app = FastAPI()
Fastuator(app)  # That's it!

Available Endpoints:

Endpoint	Description
GET /fastuator/health	Aggregated health status with optional details
GET /fastuator/liveness	Kubernetes liveness probe (critical checks only)
GET /fastuator/readiness	Kubernetes readiness probe (all dependencies)
GET /fastuator/metrics	Prometheus-compatible metrics
GET /fastuator/info	Application and system information

📖 Usage

Basic Setup

from fastapi import FastAPI
from fastuator import Fastuator

app = FastAPI()

# Use default configuration
Fastuator(app)

# Custom prefix
Fastuator(app, prefix="/monitoring")

Custom Health Checks

from fastuator import Fastuator

app = FastAPI()

# Define custom health checks
async def database_health():
    try:
        # Check database connection
        await db.execute("SELECT 1")
        return {"status": "UP", "database": "connected"}
    except Exception as e:
        return {"status": "DOWN", "database": str(e)}

async def redis_health():
    try:
        await redis.ping()
        return {"status": "UP", "redis": "connected"}
    except Exception:
        return {"status": "DOWN", "redis": "unreachable"}

# Register custom checks
Fastuator(
    app,
    health_checks=[database_health, redis_health],
    readiness_checks=[database_health, redis_health],
    liveness_checks=[],  # No external dependencies for liveness
)

Health Check Response

Without details:

curl http://localhost:8000/fastuator/health

{"status": "UP"}

With details:

curl http://localhost:8000/fastuator/health?show_details=true

{
  "status": "UP",
  "components": {
    "check_0": {
      "status": "UP",
      "cpu_percent": 45.2
    },
    "check_1": {
      "status": "UP",
      "memory_percent": 62.1,
      "memory_available_mb": 4096
    }
  }
}

☸️ Kubernetes Integration

Deployment Example

apiVersion: apps/v1
kind: Deployment
metadata:
  name: fastapi-app
spec:
  template:
    spec:
      containers:
      - name: app
        image: myapp:latest
        ports:
        - containerPort: 8000
        livenessProbe:
          httpGet:
            path: /fastuator/liveness
            port: 8000
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /fastuator/readiness
            port: 8000
          initialDelaySeconds: 5
          periodSeconds: 5

📊 Prometheus Metrics

Fastuator automatically collects the following metrics:

• http_requests_total: Total HTTP requests (counter)
• http_request_duration_seconds: Request duration histogram
• app_health_status: Health status gauge (1=UP, 0=DOWN)

Scrape configuration:

scrape_configs:
  - job_name: 'fastapi'
    static_configs:
      - targets: ['localhost:8000']
    metrics_path: '/fastuator/metrics'

⚙️ Configuration

Fastuator(
    app,
    prefix="/fastuator",              # URL prefix for all endpoints
    health_checks=[...],               # List of health check functions
    liveness_checks=[...],             # Checks for liveness probe
    readiness_checks=[...],            # Checks for readiness probe
    enable_metrics=True,               # Enable Prometheus metrics
)

🧪 Built-in Health Checks

Fastuator includes these health checks by default:

• CPU Usage: Reports DOWN if CPU > 90%
• Memory Usage: Reports DOWN if memory > 90%
• Disk Usage: Reports DOWN if disk > 90%

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests (pytest --cov=fastuator)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Inspired by Spring Boot Actuator.

📚 Related Projects

• FastAPI - Modern web framework for Python
• Prometheus - Monitoring and alerting toolkit
• Kubernetes - Container orchestration platform

⭐ Loved this library? Star us to support!