In this lesson, you will learn how to design an HTTP-based health check API that aggregates and reports the real-time operational status of multiple distributed WebSocket worker nodes.
The Problem: Visibility in Distributed Systems
In a clustered environment, you have multiple Node.js processes handling WebSocket connections. Because WebSockets are stateful, a standard load balancer check—which usually just hits a single endpoint—might miss an "incident" where one specific worker has become unresponsive, even if the primary HTTP server process is still alive.
The Solution: The Heartbeat Registry
To solve this, we implement a "Heartbeat-based Health Check." Each worker process periodically emits a pulse—a timestamped object—to a shared state store (like Redis). The "Health Check API" then acts as an aggregator that queries this store, inspects the timestamps, and verifies the vitality of every registered node.
Consider this simplified pattern for your monitoring endpoint:
// Inside your Express health-check controller
app.get('/health/workers', async (req, res) => {
const workers = await redis.hgetall('worker_heartbeats');
const now = Date.now();
const statusReport = {};
for (const [workerId, lastSeen] of Object.entries(workers)) {
// If heartbeat is older than 10 seconds, mark as unhealthy
const isAlive = (now - parseInt(lastSeen)) < 10000;
statusReport[workerId] = isAlive ? 'healthy' : 'unresponsive';
}
res.json(statusReport);
});
Why This Matters
By exposing this data via a standard HTTP API, you can integrate your cluster health directly into infrastructure monitoring tools (like Datadog or Prometheus). If a specific worker stops sending its heartbeat, your API will reflect that unresponsive state, allowing your orchestration layer to restart that specific process or reroute connections before users notice the disconnect.
Unlike the high-frequency event emitters we discussed previously, your heartbeat intervals should be conservative—usually every 3 to 5 seconds—to prevent overwhelming your shared data store while still providing sub-10-second failure detection.
Key Takeaway: A heartbeat-based health check turns "silent" WebSocket worker failures into visible metrics, ensuring your cluster maintains high availability by detecting node unresponsiveness in real-time.