HealthCheckPlugin Schema

Schema definition for the Health Check Plugin, which provides health monitoring endpoints for application status and readiness checks.

Schema Information

Properties

Usage Examples

Basic Health Check (Default Endpoints)

<tr itemscope itemtype="https://rustybeam.net/schema/HealthCheckPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_health_check.so</span>
</tr>

Custom Endpoints with Monitoring

<tr itemscope itemtype="https://rustybeam.net/schema/HealthCheckPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_health_check.so</span>
    <span itemprop="health_endpoint">/status</span>
    <span itemprop="ready_endpoint">/ready</span>
    <span itemprop="live_endpoint">/ping</span>
    <span itemprop="detailed_checks">true</span>
    <span itemprop="check_disk_space">true</span>
    <span itemprop="min_disk_space_mb">500</span>
</tr>

Simple Health Check (No Details)

<tr itemscope itemtype="https://rustybeam.net/schema/HealthCheckPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_health_check.so</span>
    <span itemprop="health_endpoint">/health</span>
    <span itemprop="detailed_checks">false</span>
    <span itemprop="check_disk_space">false</span>
    <span itemprop="name">simple_health</span>
</tr>

Kubernetes-style Health Checks

<tr itemscope itemtype="https://rustybeam.net/schema/HealthCheckPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_health_check.so</span>
    <span itemprop="health_endpoint">/healthz</span>
    <span itemprop="ready_endpoint">/readiness</span>
    <span itemprop="live_endpoint">/liveness</span>
    <span itemprop="detailed_checks">true</span>
</tr>

Health Check Endpoints

Health Endpoint (/health)

Purpose: General application health status

Use Case: Overall application monitoring, load balancer health checks

GET /health
HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "healthy",
  "timestamp": "2025-07-10T14:30:45Z",
  "uptime_seconds": 3600,
  "checks": {
    "disk_space": "healthy",
    "memory": "healthy"
  },
  "details": {
    "disk_free_mb": 2048,
    "version": "1.0.0"
  }
}

Readiness Endpoint (/ready)

Purpose: Application readiness to receive traffic

Use Case: Kubernetes readiness probes, traffic routing decisions

GET /ready
HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ready",
  "timestamp": "2025-07-10T14:30:45Z",
  "ready": true
}

Liveness Endpoint (/live)

Purpose: Application liveness check

Use Case: Kubernetes liveness probes, restart decisions

GET /live
HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "alive",
  "timestamp": "2025-07-10T14:30:45Z",
  "alive": true
}

Health Status Types

Schema Inheritance

This schema inherits from the UtilityPlugin schema, which provides:

• logfile - Log file path
• directory - Directory configuration
• enabled - Plugin enable/disable state

And ultimately from the base Plugin schema, which provides:

• library - Plugin library path
• plugin - Base plugin reference property

System Checks Performed

When detailed_checks is enabled, the plugin performs these system checks:

• Disk Space: Checks available disk space against min_disk_space_mb
• Memory Usage: Monitors system memory availability
• Uptime: Reports application uptime since start
• Response Time: Measures health check response latency
• Process Status: Verifies application is responding normally

Validation Rules

• Endpoint paths should start with "/" and be valid URL paths
• detailed_checks and check_disk_space must be "true" or "false" if specified
• min_disk_space_mb must be a positive integer
• Endpoint paths should be unique (no duplicate paths)
• The name property should be unique if multiple health check plugins are used

Monitoring Integration

Kubernetes Integration

apiVersion: v1
kind: Pod
spec:
  containers:
  - name: rusty-beam
    livenessProbe:
      httpGet:
        path: /live
        port: 3000
      initialDelaySeconds: 30
      periodSeconds: 10
    readinessProbe:
      httpGet:
        path: /ready
        port: 3000
      initialDelaySeconds: 5
      periodSeconds: 5

Docker Health Check

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

Load Balancer Integration

# nginx upstream health check
upstream backend {
    server backend1:3000;
    server backend2:3000;
    health_check uri=/ready;
}

Alerting and Monitoring

Prometheus Integration

Health check endpoints can be scraped by monitoring systems:

# Monitor health status
up{job="rusty-beam"} = 1 if /health returns 200
health_check_duration_seconds = response time for /health
disk_free_bytes = available disk space from /health details

Common Monitoring Queries

• Uptime: Track application restart frequency
• Response Time: Monitor health check latency trends
• Disk Usage: Alert when free space is low
• Status Changes: Alert on healthy → unhealthy transitions

Integration with Other Plugins

• Access Log Plugin: Logs health check requests (can filter them out)
• Rate Limit Plugin: May want to exempt health checks from rate limiting
• CORS Plugin: Allow cross-origin health check requests if needed
• Authorization Plugin: Health checks usually bypass authentication
• Compression Plugin: Health responses are typically small (may skip compression)

Troubleshooting

See Also

• UtilityPlugin Schema - Parent schema
• Health Check Plugin Documentation - Complete plugin documentation
• AccessLogPlugin Schema - Monitoring integration
• RateLimitPlugin Schema - Rate limiting considerations