Skip to content
HeliosDB Full

HeliosDB Health Check Guide

HeliosDB Health Check Guide

Version: 1.0 Last Updated: 2025-11-30

Health Check Endpoints

HTTP Endpoint

Terminal window
# Simple health check
curl http://localhost:5432/health
# Returns: 200 OK if healthy


# Detailed health check
curl http://localhost:5432/health/detailed
# Returns: JSON with full status

Response Format

{
  "status": "healthy",
  "timestamp": "2025-11-30T10:00:00Z",
  "version": "7.0.0",
  "components": {
    "database": "healthy",
    "replication": "healthy",
    "cache": "healthy",
    "storage": "healthy"
  },
  "metrics": {
    "uptime_seconds": 86400,
    "connections": 42,
    "memory_usage_pct": 45.2,
    "disk_usage_pct": 62.5,
    "cpu_usage_pct": 12.3
  }
}

Health Check SQL Commands

-- Database health
SELECT pg_is_in_recovery() as is_replica;


-- Replication health
SELECT COUNT(*) as replica_count FROM pg_stat_replication;


-- Cache health
SELECT cache_hit_rate FROM cache_statistics;


-- Storage health
SELECT pg_database_size(current_database()) / 1024 / 1024 / 1024 as size_gb;


-- Vacuum/ANALYZE status
SELECT
  schemaname,
  tablename,
  last_vacuum,
  last_analyze
FROM pg_stat_user_tables
ORDER BY last_vacuum DESC;

Monitoring Integration

Prometheus Metrics

# HELP heliosdb_up Database is up
# TYPE heliosdb_up gauge
heliosdb_up 1


# HELP heliosdb_connections Active connections
# TYPE heliosdb_connections gauge
heliosdb_connections 42


# HELP heliosdb_memory_usage_bytes Memory usage
# TYPE heliosdb_memory_usage_bytes gauge
heliosdb_memory_usage_bytes 1073741824

Kubernetes Probes

livenessProbe:
  httpGet:
    path: /health
    port: 5432
  initialDelaySeconds: 30
  periodSeconds: 10


readinessProbe:
  httpGet:
    path: /health/ready
    port: 5432
  initialDelaySeconds: 5
  periodSeconds: 5

Alerting Rules

# Alert if database is down
- alert: HeliosDBDown
  expr: heliosdb_up == 0
  for: 1m
  annotations:
    summary: "HeliosDB is down"


# Alert if memory usage high
- alert: HighMemoryUsage
  expr: heliosdb_memory_usage_pct > 80
  for: 5m
  annotations:
    summary: "High memory usage"


# Alert if replication lag
- alert: ReplicationLag
  expr: heliosdb_replication_lag_bytes > 1073741824
  for: 1m
  annotations:
    summary: "Replication lag detected"

Troubleshooting

Issue: Health check returns unhealthy

-- Check what's unhealthy
SELECT * FROM health_check_details;


-- Check specific components
SELECT * FROM component_health_status;


-- Review logs
SELECT * FROM system_logs WHERE severity = 'ERROR'
ORDER BY timestamp DESC LIMIT 20;

Best Practices

  1. Check health every 30 seconds
  2. Set up alerts for failures
  3. Monitor trends over time
  4. Include in deployment checks
  5. Test failover with health checks

Related Documentation: