Health Checks API

Monitor system health, queue status, and batch writer activity.

GET
/functions/v1/health
Basic liveness check. Returns 200 OK if the service is running.

Authentication

No authentication required

Responses

200Service is healthy
{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00Z",
  "message": "Service is up"
}
GET
/functions/v1/health/ready
Readiness check. Returns 200 if the service can accept traffic, 503 if degraded or unhealthy.

Authentication

No authentication required

Responses

200Service is ready
{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00Z",
  "checks": {
    "queue": {
      "depth": 1234
    },
    "writer": {
      "status": "healthy"
    }
  }
}
503Service is not ready
{
  "status": "unhealthy",
  "timestamp": "2025-01-15T10:30:00Z",
  "checks": {
    "queue": {
      "depth": 75000
    },
    "writer": {
      "status": "unhealthy"
    }
  }
}
GET
/functions/v1/health/queue
Queue health metrics including depth and oldest item age.

Authentication

No authentication required

Responses

200Queue health information
{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00Z",
  "checks": {
    "queue": {
      "depth": 1234,
      "oldest_item_age_seconds": 5
    }
  }
}
GET
/functions/v1/health/writer
Batch writer health including last run time and duration.

Authentication

No authentication required

Responses

200Batch writer health information
{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00Z",
  "checks": {
    "writer": {
      "last_run": "2025-01-15T10:29:58Z",
      "last_duration_ms": 250,
      "seconds_since_run": 2
    }
  }
}
GET
/functions/v1/health/partitions
Partition status for daily log partitions.

Authentication

No authentication required

Responses

200Partition health information
{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00Z",
  "checks": {
    "partitions": {
      "current_partition": "logs_2025_01_15",
      "current_exists": true,
      "next_partition": "logs_2025_01_16",
      "next_exists": true
    }
  }
}
GET
/functions/v1/health/detailed
Comprehensive health check combining all health metrics.

Authentication

No authentication required

Responses

200Detailed health information
{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00Z",
  "checks": {
    "queue": {
      "depth": 1234,
      "oldest_item_age_seconds": 5
    },
    "writer": {
      "last_run": "2025-01-15T10:29:58Z",
      "last_duration_ms": 250
    },
    "partitions": {
      "current_partition": "logs_2025_01_15",
      "current_exists": true,
      "next_partition": "logs_2025_01_16",
      "next_exists": true
    }
  }
}
503Service is unhealthy

Health Status Values

healthy

System is operating normally. All checks pass.

degraded

System is operational but experiencing some issues. May indicate high queue depth or slow batch processing.

unhealthy

System is not operating normally. Critical checks are failing. Service may not be able to process requests.

Monitoring Integration

Health check endpoints can be used with monitoring tools like Prometheus, Datadog, or custom health check services.

# Example: Prometheus health check
- job_name: 'lightning-logs-health'
  metrics_path: '/functions/v1/health/ready'
  static_configs:
    - targets: ['your-project.supabase.co']