WebSocket Monitoring Guide: Uptime, Latency & Connection Health (2026)

How WebSockets Fail (And What to Monitor)

WebSocket failures fall into three categories, each requiring different monitoring approaches:

Layer 1: WebSocket Connectivity Check

The most basic check: can a client establish a WebSocket connection? This verifies the upgrade handshake, TLS (for wss://), and that the server is accepting connections.

// Node.js WebSocket connectivity check
const WebSocket = require('ws');

function checkWebSocket(url, timeout = 5000) {
  return new Promise((resolve, reject) => {
    const ws = new WebSocket(url);
    const timer = setTimeout(() => {
      ws.terminate();
      reject(new Error('Connection timeout'));
    }, timeout);

    ws.on('open', () => {
      clearTimeout(timer);
      ws.close(1000, 'health check');
      resolve({ status: 'healthy', latency: Date.now() - startTime });
    });

    ws.on('error', (err) => {
      clearTimeout(timer);
      reject(err);
    });

    const startTime = Date.now();
  });
}

// Usage
checkWebSocket('wss://api.example.com/ws')
  .then(result => console.log('Healthy:', result))
  .catch(err => console.error('ALERT:', err.message));

Verifying the 101 Upgrade Response

A successful WebSocket connection returns HTTP 101 Switching Protocols. If you see HTTP 200, 400, or 426 instead, the server isn't accepting WebSocket upgrades. Common causes: reverse proxy not configured for WebSocket, missing Upgrade: websocket header passthrough in nginx/Caddy, or TLS termination stripping upgrade headers.

Layer 2: Message Round-Trip Latency

Connectivity checks verify the connection was established. Message latency checks verify that messages are actually flowing through the application layer — not just that the TCP connection is alive.

// WebSocket ping/pong latency check
function checkWebSocketLatency(url, testMessage) {
  return new Promise((resolve, reject) => {
    const ws = new WebSocket(url);

    ws.on('open', () => {
      const sentAt = Date.now();
      ws.send(JSON.stringify({ type: 'ping', id: sentAt }));

      ws.on('message', (data) => {
        const msg = JSON.parse(data);
        if (msg.type === 'pong' && msg.id === sentAt) {
          const latency = Date.now() - sentAt;
          ws.close(1000);
          resolve({ latency, timestamp: new Date() });
        }
      });
    });

    setTimeout(() => {
      ws.terminate();
      reject(new Error('Ping timeout — no pong received'));
    }, 10000);
  });
}

Alert if P95 message latency exceeds your SLA threshold. For real-time applications, this is typically <100ms. For chat applications, <500ms. For financial data feeds, often <50ms.

Layer 3: Connection Lifecycle Metrics

Key Metrics to Track Server-Side

• Active connections over time: Track the count of currently open WebSocket connections. Sudden drops indicate mass disconnections. Unexpected growth indicates connection leaks (connections not being properly closed).
• Connection duration distribution: How long do connections stay open? Very short connections (<10 seconds) in large volumes may indicate clients connecting and immediately failing.
• Reconnection rate: Track how often clients reconnect. A client that connects, drops, and reconnects every few seconds is experiencing instability — this may not be visible in your raw connection count.
• Close code distribution: Track WebSocket close codes across all disconnections. Alert on increasing rates of error codes (1006, 1011).

WebSocket Close Codes Reference

Layer 4: Keepalive and Silent Drop Detection

WebSocket connections can appear alive at the TCP level while silently failing to deliver messages. This happens when:

• A network device drops the connection silently (NAT timeout, firewall idle-connection limit)
• A load balancer closes idle connections without sending a close frame
• A server-side bug consumes the connection but stops processing messages

The solution: implement application-level heartbeats. Every 30-60 seconds, the server sends a ping (or custom "heartbeat" message). If the client doesn't respond within a timeout, close the connection and log it as a silent drop. This makes invisible failures visible.

// Server-side heartbeat implementation (Node.js/ws)
const HEARTBEAT_INTERVAL = 30000; // 30 seconds
const HEARTBEAT_TIMEOUT = 10000;  // 10 seconds to respond

wss.on('connection', (ws) => {
  ws.isAlive = true;

  ws.on('pong', () => {
    ws.isAlive = true; // Mark alive on pong response
  });

  const heartbeatTimer = setInterval(() => {
    if (!ws.isAlive) {
      console.log('Silent drop detected — terminating');
      silentDropCounter.inc(); // Prometheus counter
      return ws.terminate();
    }
    ws.isAlive = false;
    ws.ping(); // WebSocket protocol ping
  }, HEARTBEAT_INTERVAL);

  ws.on('close', () => clearInterval(heartbeatTimer));
});

Nginx Configuration for WebSocket Proxying

A common source of WebSocket monitoring failures is a reverse proxy stripping the upgrade headers. Proper nginx configuration:

# nginx.conf — required for WebSocket proxying
location /ws {
    proxy_pass http://websocket_backend;
    proxy_http_version 1.1;

    # Required for WebSocket upgrade
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    # Increase timeout — WebSockets are long-lived
    proxy_read_timeout 3600s;  # 1 hour
    proxy_send_timeout 3600s;

    # Pass real client IP
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

WebSocket Monitoring Checklist

Frequently Asked Questions

Related Guides

• GraphQL API Monitoring Guide
• API Monitoring at Scale
• What Are Webhooks?
• API Health Check Endpoint Guide
• Circuit Breaker Pattern