tutorial

Uptime monitoring for Centrifugo real-time messaging server

Centrifugo powers the real-time layer for your application — chat systems, live feeds, collaborative tools, multiplayer games. When Centrifugo goes down, you...

Centrifugo powers the real-time layer for your application — chat systems, live feeds, collaborative tools, multiplayer games. When Centrifugo goes down, your WebSocket connections drop, your SSE streams go silent, and users see a frozen UI. Because Centrifugo sits between your application and your users, a failure here is immediately visible at scale.

This tutorial covers production-grade uptime monitoring for Centrifugo using Vigilmon. We will walk through:

  • Monitoring the Centrifugo /health endpoint
  • Monitoring WebSocket port availability via TCP check
  • Monitoring the Centrifugo server API
  • Heartbeat monitoring for scheduled Centrifugo jobs
  • SSL certificate monitoring

Prerequisites

  • Centrifugo 4.x or 5.x running (Docker, bare metal, or Kubernetes)
  • A free account at vigilmon.online

Part 1: The Centrifugo health endpoint

Centrifugo ships with a built-in /health endpoint that returns HTTP 200 when the server is operational. It is the primary signal for external monitoring tools.

Enable the health endpoint

By default the health endpoint is enabled. Confirm it is accessible in your Centrifugo config (config.json or environment variables):

{
  "http_server": {
    "port": 8000
  },
  "health": true
}

Or with the environment variable approach:

CENTRIFUGO_HEALTH=true
CENTRIFUGO_PORT=8000

Verify the health endpoint

curl http://localhost:8000/health

Expected response:

{}

Centrifugo returns HTTP 200 with an empty JSON object {} when healthy. Any non-200 response indicates a problem.

Docker Compose example

# docker-compose.yml
version: "3.8"

services:
  centrifugo:
    image: centrifugo/centrifugo:v5
    command: centrifugo
    environment:
      - CENTRIFUGO_TOKEN_HMAC_SECRET_KEY=your-secret-key
      - CENTRIFUGO_API_KEY=your-api-key
      - CENTRIFUGO_HEALTH=true
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8000/health"]
      interval: 30s
      timeout: 5s
      retries: 3

Part 2: HTTP monitoring in Vigilmon

Monitor the health endpoint

  1. Log in to vigilmon.online and click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: https://centrifugo.example.com/health
  4. Set interval to 1 minute.
  5. Set expected HTTP status to 200.
  6. Click Save.

Because the health response body is {}, a keyword check is optional — HTTP 200 is sufficient confirmation that the Centrifugo process is up and its HTTP layer is responding.

Monitor the Centrifugo info endpoint

The /info endpoint (requires API key authentication) reports node statistics — connected clients, channels, subscriptions. You can monitor it as a deeper health check:

curl -H "Authorization: apikey your-api-key" \
  http://localhost:8000/api/info

Expected response:

{
  "result": {
    "nodes": [
      {
        "uid": "node-uuid",
        "name": "centrifugo",
        "num_clients": 42,
        "num_channels": 8,
        "version": "5.0.0"
      }
    ]
  }
}

To monitor this in Vigilmon, add a custom header Authorization: apikey your-api-key and set a keyword check for "nodes".

Part 3: TCP port monitoring for WebSocket availability

Centrifugo's core value is WebSocket connectivity. Even if the HTTP health endpoint is responding, the WebSocket upgrade path can be broken by a misconfigured reverse proxy or a firewall rule. A TCP check on the WebSocket port catches this class of failure independently of the HTTP layer.

  1. In Vigilmon, click Add Monitor.
  2. Choose TCP monitor.
  3. Enter host: centrifugo.example.com and port: 8000 (or your WebSocket port).
  4. Set interval to 1 minute.
  5. Click Save.

If you run WebSocket traffic on a separate port from the HTTP API, add two TCP monitors — one for each port.

Part 4: Heartbeat monitoring for Centrifugo scheduled jobs

Centrifugo is often used with cron-like scheduled tasks that push messages to channels on a schedule — price updates, notification batches, feed refreshes. If a scheduled publisher stops running, channels go stale without any error visible at the infrastructure layer.

Set up a Vigilmon heartbeat monitor

  1. In Vigilmon, click Add Monitor.
  2. Choose Heartbeat monitor.
  3. Name it: Centrifugo channel publisher.
  4. Set interval to match your publish schedule (e.g., 5 minutes).
  5. Copy the generated heartbeat URL.

Ping the heartbeat from your publisher

Add a Vigilmon ping at the end of your scheduled publish job. The exact implementation depends on your publisher language, but the pattern is the same — send an HTTP GET to the heartbeat URL after successful message delivery:

# Python example: scheduled Centrifugo publisher
import httpx
from cent import Client

CENTRIFUGO_API_URL = "http://localhost:8000/api"
CENTRIFUGO_API_KEY = "your-api-key"
VIGILMON_HEARTBEAT_URL = "https://vigilmon.online/heartbeat/your-heartbeat-id"

def publish_price_update():
    client = Client(CENTRIFUGO_API_URL, api_key=CENTRIFUGO_API_KEY)
    client.publish("prices", {"symbol": "BTCUSD", "price": 65000})
    # Signal successful completion to Vigilmon
    httpx.get(VIGILMON_HEARTBEAT_URL, timeout=5)

publish_price_update()

// TypeScript/Node.js example
import { Centrifuge } from 'centrifuge';
import axios from 'axios';

const VIGILMON_HEARTBEAT_URL = process.env.VIGILMON_HEARTBEAT_URL!;

async function publishUpdate() {
  // Your Centrifugo server API publish call
  await fetch('http://localhost:8000/api/publish', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `apikey ${process.env.CENTRIFUGO_API_KEY}`,
    },
    body: JSON.stringify({
      channel: 'notifications',
      data: { message: 'New update available' },
    }),
  });

  // Ping Vigilmon heartbeat
  await axios.get(VIGILMON_HEARTBEAT_URL);
}

If Vigilmon does not receive a ping within the configured interval, it alerts you that your publisher has stopped running — even though Centrifugo itself is healthy.

Part 5: SSL certificate monitoring

If Centrifugo is exposed over HTTPS (directly or through a reverse proxy like Nginx or Caddy), certificate expiry will take your WebSocket connections down without warning. Let's Encrypt certificates expire every 90 days, and renewal failures are common when DNS changes or rate limits are hit.

  1. In Vigilmon, click Add Monitor.
  2. Choose SSL monitor.
  3. Enter: centrifugo.example.com
  4. Set alert threshold to 14 days before expiry.
  5. Add your alert channel.

Add a separate SSL monitor for each domain that serves Centrifugo traffic (e.g., if your WebSocket endpoint is wss://ws.example.com and your API is on https://api.example.com).

Part 6: Webhook alerts

Wire Vigilmon events to your incident pipeline so your team is notified the moment Centrifugo goes down:

// Express.js webhook receiver
import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook/vigilmon', (req, res) => {
  const { monitor_name, status, url, response_code, checked_at } = req.body;

  if (status === 'down') {
    console.error('[VIGILMON] Centrifugo DOWN', {
      monitor: monitor_name,
      url,
      code: response_code,
      at: checked_at,
    });
    // Trigger PagerDuty / Slack / OpsGenie alert
    notifyOnCall({ monitor: monitor_name, url });
  } else if (status === 'up') {
    console.info('[VIGILMON] Centrifugo recovered', { monitor: monitor_name });
  }

  res.sendStatus(204);
});

Vigilmon sends this payload on DOWN and UP transitions:

{
  "monitor_id": "mon_abc123",
  "monitor_name": "Centrifugo /health",
  "status": "down",
  "url": "https://centrifugo.example.com/health",
  "checked_at": "2026-06-30T08:01:00Z",
  "response_code": 503,
  "response_time_ms": 1502
}

Part 7: Kubernetes deployments

If Centrifugo runs in Kubernetes, expose the health endpoint through a Service and monitor it via an Ingress:

apiVersion: v1
kind: Service
metadata:
  name: centrifugo
  namespace: default
spec:
  selector:
    app: centrifugo
  ports:
    - name: http
      port: 8000
      targetPort: 8000
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: centrifugo
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
    - hosts:
        - centrifugo.example.com
      secretName: centrifugo-tls
  rules:
    - host: centrifugo.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: centrifugo
                port:
                  number: 8000

Add a liveness probe in your Deployment so Kubernetes restarts unhealthy pods:

livenessProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 10
  periodSeconds: 30
readinessProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 5
  periodSeconds: 10

Then point Vigilmon at https://centrifugo.example.com/health as described in Part 2.

Summary

Your Centrifugo deployment now has four layers of monitoring:

  1. /health HTTP monitor — confirms Centrifugo is alive, polled every 60 seconds.
  2. TCP port monitor — verifies the WebSocket port is reachable independently of the HTTP layer.
  3. Heartbeat monitor — catches silent failures in scheduled channel publishers without infrastructure-level errors.
  4. SSL monitor — alerts you 14 days before certificate expiry, before WebSocket connections start failing for users.

Vigilmon handles check scheduling, multi-region polling, alert routing, and uptime history — your team gets notified within 60 seconds of any Centrifugo failure.

Monitor your Centrifugo server free at vigilmon.online

#centrifugo #websocket #realtime #monitoring #devops

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles