Monitoring Server Health

The STAT command provides a real-time snapshot of server health metrics. Use it to verify the server is running correctly, detect connection leaks, and inspect the execution pipeline.

Checking Server Status#

echo 'req-1 STAT' | socat - TCP:localhost:5678

Response:

req-1 uptime_ns 60000000000
req-1 connections 1
req-1 jobs_total 42
req-1 jobs_planned 30
req-1 jobs_triggered 2
req-1 jobs_executed 8
req-1 jobs_failed 2
req-1 rules_total 5
req-1 executions_pending 0
req-1 executions_inflight 0
req-1 persistence logfile
req-1 compression idle
req-1 auth_enabled 0
req-1 tls_enabled 0
req-1 framerate 512
req-1 OK

Understanding the Metrics#

Server State#

Job Counts#

Execution Pipeline#

A growing executions_pending value indicates the processor thread cannot keep up with triggered jobs.

Infrastructure#

Scripting Health Checks#

STAT returns metrics in a fixed order, making it reliable for scripting:

# Extract a specific metric
echo 'r1 STAT' | socat - TCP:localhost:5678 | grep 'r1 connections' | awk '{print $3}'

# Simple health check script
#!/bin/bash
response=$(echo 'hc STAT' | socat - TCP:localhost:5678 2>/dev/null)
if echo "$response" | grep -q 'hc OK'; then
    echo "Server is healthy"
else
    echo "Server unreachable"
    exit 1
fi

Notes#

• STAT is read-only — it does not write to the persistence logfile.
• STAT is namespace-independent — any authenticated client can call it.
• When authentication is enabled, STAT requires authentication like any other command.
• Extra arguments after STAT are silently ignored.
• See the Protocol Reference for the full specification.