Health API¶

The Health API provides endpoints for monitoring system health, checking service readiness, and managing resilience patterns like circuit breakers and graceful degradation.

Overview¶

CalcBridge health monitoring supports:

• Liveness Probes: Simple process health for Kubernetes
• Readiness Probes: Dependency health (database, cache, broker)
• Deep Health Checks: Comprehensive multi-component status
• Circuit Breaker Management: Monitor and reset service circuit breakers
• Graceful Degradation: Feature flag and fallback management
• Maintenance Mode: Controlled service degradation

Basic Health Endpoints¶

Health Check¶

Basic health check returning system status.

GET /health

Response¶

{
  "status": "healthy",
  "version": "1.2.0",
  "timestamp": "2026-01-25T10:30:00Z"
}

Readiness Check¶

Readiness check including dependency health.

GET /health/ready

Response¶

{
  "status": "ready",
  "version": "1.2.0",
  "timestamp": "2026-01-25T10:30:00Z",
  "checks": {
    "database": {
      "status": "ok",
      "message": "Connection pool healthy"
    },
    "valkey": {
      "status": "ok",
      "message": "Connected"
    }
  }
}

When a dependency is unhealthy:

{
  "status": "not_ready",
  "version": "1.2.0",
  "timestamp": "2026-01-25T10:30:00Z",
  "checks": {
    "database": {
      "status": "error",
      "message": "Connection timeout after 5s"
    },
    "valkey": {
      "status": "ok",
      "message": "Connected"
    }
  }
}

Liveness Check¶

Simple liveness check for Kubernetes probes.

GET /health/live

Response¶

{
  "status": "alive"
}

Detailed Health Check¶

Comprehensive health check with all component statuses.

GET /health/detailed

Enhanced Health Endpoints¶

Deep Health Check¶

Comprehensive health check including all dependencies.

GET /health/deep

Resilience Status¶

Get status of circuit breakers and bulkheads.

GET /health/resilience

Degradation Status¶

Get current graceful degradation status.

GET /health/degradation

Full Degradation Status¶

Complete graceful degradation status with all fallback information.

GET /health/degradation/full

Degradation History¶

Get recent degradation events.

GET /health/degradation/history

Query Parameters¶

Circuit Breaker Management¶

Get Circuit Breaker Status¶

Get detailed circuit breaker metrics for a specific service.

GET /health/circuit-breaker/{service}

Path Parameters¶

Reset Circuit Breaker¶

Reset a circuit breaker to closed state.

POST /health/reset/{service}

Reset All Circuit Breakers¶

Reset all circuit breakers to closed state.

POST /health/reset-all

Get All Service Health¶

Returns health status for all services with circuit breaker info.

GET /health/services

Maintenance Mode¶

Toggle Maintenance Mode¶

Enter or exit maintenance mode.

POST /health/maintenance

Query Parameters¶

Feature Flags¶

Get All Feature Flags¶

Get current status of all feature flags.

GET /health/feature-flags

Update Feature Flags¶

Update feature flags.

POST /health/feature-flags

Cache Management¶

Get Fallback Cache Status¶

Get in-memory fallback cache statistics.

GET /health/fallback-cache

Clear Fallback Cache¶

Clear all entries from the fallback cache.

POST /health/fallback-cache/clear

Task Queue Monitoring¶

Get Sync Task Fallback Status¶

Get synchronous task fallback configuration and stats.

GET /health/sync-fallback

Get Celery Queue Depths¶

Get current depth of all Celery task queues.

GET /health/queue-depths

Response¶

{
  "queues": {
    "default": 3,
    "calculate": 0,
    "parse": 1,
    "priority": 0,
    "export": 2
  },
  "total_pending": 6,
  "timestamp": "2026-01-25T10:30:00Z"
}

Kubernetes Integration¶

Configure health probes in your deployment:

livenessProbe:
  httpGet:
    path: /health/live
    port: 8000
  initialDelaySeconds: 10
  periodSeconds: 15

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

startupProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 3
  failureThreshold: 30
  periodSeconds: 10

Related Documentation¶

• Metrics API - Prometheus metrics endpoint
• Dead Letter Queue API - Failed task management
• Architecture - System Design - Health check architecture