Health Check

Overview

The health check endpoint provides a simple way to verify that the API server is running and responsive. Use this for monitoring, load balancer health checks, and readiness probes.

Endpoint

GET /health

Authentication

No authentication required - This endpoint is publicly accessible.

Request

Simple GET request with no parameters:

curl http://localhost:7100/health

Response

Healthy Response

HTTP Status: 200 OK

{
  "status": "healthy"
}

Unhealthy Response

HTTP Status: 503 Service Unavailable

{
  "status": "unhealthy",
  "reason": "No ASR workers available"
}

Use Cases

Load Balancer Health Checks

Configure your load balancer to use the health endpoint:

apiServer:
  service:
    type: LoadBalancer
    healthCheckPath: /health
    healthCheckInterval: 30
    healthCheckTimeout: 5
    healthyThreshold: 2
    unhealthyThreshold: 3

Kubernetes Liveness Probe

Monitor pod health in Kubernetes:

livenessProbe:
  httpGet:
    path: /health
    port: 7100
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

Kubernetes Readiness Probe

Determine when pod is ready to receive traffic:

readinessProbe:
  httpGet:
    path: /health
    port: 7100
  initialDelaySeconds: 10
  periodSeconds: 5
  timeoutSeconds: 3
  failureThreshold: 3

Monitoring and Alerting

Monitor service availability:

- job_name: 'api-server-health'
  metrics_path: '/health'
  scrape_interval: 30s
  static_configs:
    - targets: ['api-server:7100']

Uptime Monitoring

Integration with uptime monitoring services:

Advanced Health Checks

Detailed Health Status

For more detailed health information, add query parameter:

curl http://localhost:7100/health?detailed=true

Response:

{
  "status": "healthy",
  "components": {
    "api_server": "healthy",
    "lightning_asr": "healthy",
    "license_proxy": "healthy",
    "redis": "healthy"
  },
  "uptime_seconds": 86400,
  "version": "1.0.0"
}

Component-Specific Checks

Check individual components:

curl http://localhost:7100/health/asr
curl http://localhost:7100/health/license
curl http://localhost:7100/health/redis

Integration Examples

Docker Compose Healthcheck

services:
  api-server:
    image: quay.io/smallestinc/self-hosted-api-server:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7100/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  template:
    spec:
      containers:
      - name: api-server
        image: quay.io/smallestinc/self-hosted-api-server:latest
        livenessProbe:
          httpGet:
            path: /health
            port: 7100
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 7100
          initialDelaySeconds: 10
          periodSeconds: 5

Automated Testing

Include health checks in CI/CD:

- name: Wait for deployment
  run: |
    for i in {1..30}; do
      if curl -f http://api.example.com/health; then
        echo "Service is healthy"
        exit 0
      fi
      sleep 10
    done
    echo "Service failed to become healthy"
    exit 1

Best Practices

healthcheck:
  timeout: 5s
  interval: 30s
  retries: 3

kubectl delete pod api-server-xxx

Troubleshooting

Health Check Failing

Check API server logs:

kubectl logs -l app=api-server -n smallest

Common causes:

• Lightning ASR not available
• License proxy down
• Redis connection failed

Solutions:

• Verify all components running
• Check service connectivity
• Review component logs

False Positives

Symptoms: Health returns 200 but requests fail

Solutions:

• Use detailed health checks
• Test actual transcription endpoint
• Monitor error rates

Timeout Issues

Symptoms: Health checks timing out

Solutions:

• Increase timeout values
• Check network latency
• Verify no network policies blocking

What’s Next?