Monitoring Mediasoup with Vigilmon

Mediasoup is a cutting-edge open-source WebRTC SFU (Selective Forwarding Unit) library for Node.js, widely used for scalable video conferencing, live streaming, and real-time collaboration platforms. Unlike monolithic media servers, Mediasoup runs C++ worker processes managed by a Node.js application — if a worker crashes, every Router and Transport on that worker goes down instantly. Vigilmon gives you external visibility into Mediasoup's application server health, WebSocket signaling port, HTTPS API, SSL certificate validity, and worker process availability so you catch failures before participants see frozen video or dropped calls.

What You'll Set Up

• HTTP health check on the Mediasoup application server health endpoint
• TCP port monitor for the WebRTC signaling WebSocket port
• SSL certificate expiry alerts for WSS and HTTPS endpoints
• Heartbeat monitor for Mediasoup worker process availability

Prerequisites

• Mediasoup application server running (Node.js with mediasoup npm package)
• Server accessible on a public hostname with HTTPS/WSS configured
• A free Vigilmon account

Step 1: Add a Health Endpoint to Your Mediasoup Application

Mediasoup does not expose a health endpoint by default — your application server (Express, Fastify, etc.) needs to expose one. Add a /health route that checks whether the Mediasoup workers are alive:

// server.js (Express example)
import express from 'express';
import { createWorker } from 'mediasoup';

const app = express();
const workers = [];

async function startWorkers() {
  const numWorkers = Object.keys(os.cpus()).length;
  for (let i = 0; i < numWorkers; i++) {
    const worker = await createWorker({
      logLevel: 'warn',
      rtcMinPort: 40000,
      rtcMaxPort: 49999,
    });

    worker.on('died', () => {
      console.error(`Mediasoup worker ${worker.pid} died, restarting...`);
      workers.splice(workers.indexOf(worker), 1);
      // restart logic here
    });

    workers.push(worker);
  }
}

// Health endpoint for Vigilmon
app.get('/health', (req, res) => {
  const aliveWorkers = workers.filter(w => !w.closed);

  if (aliveWorkers.length === 0) {
    return res.status(503).json({
      status: 'unhealthy',
      workers: 0,
      message: 'No active Mediasoup workers',
    });
  }

  res.json({
    status: 'ok',
    workers: aliveWorkers.length,
    pids: aliveWorkers.map(w => w.pid),
  });
});

await startWorkers();
app.listen(3000);

Verify the endpoint:

curl https://mediasoup.yourdomain.com/health

Expected response when healthy:

{
  "status": "ok",
  "workers": 4,
  "pids": [1234, 1235, 1236, 1237]
}

Response when all workers are dead:

{
  "status": "unhealthy",
  "workers": 0,
  "message": "No active Mediasoup workers"
}

Step 2: Monitor the Health Endpoint

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: https://mediasoup.yourdomain.com/health
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Add a keyword check: must contain "status":"ok".
7. Click Save.

The keyword check distinguishes a healthy response from a 200 returned by a load balancer or error page. If all Mediasoup workers die, the endpoint returns 503, which Vigilmon catches immediately.

Step 3: Monitor the WebSocket Signaling Port

Mediasoup clients connect via WebSocket (WSS) for signaling — exchanging SDP offers/answers and ICE candidates. This typically runs on a dedicated port or on port 443 via a path-based proxy. Monitor the TCP connectivity:

For a dedicated WebSocket port (e.g., 4443):

1. Click Add Monitor → TCP Port.
2. Host: mediasoup.yourdomain.com, Port: 4443.
3. Set Check interval to 1 minute.
4. Click Save.

If your WebSocket signaling runs over port 443 (the same as HTTPS), the HTTP monitor in Step 2 already covers TCP reachability on that port. Add a separate TCP monitor only if you use a dedicated signaling port.

A TCP failure on the signaling port means clients cannot initiate new sessions — existing sessions may survive briefly if DTLS/ICE is already established, but no new joins or reconnections will succeed.

Step 4: Monitor the HTTPS API Availability

Many Mediasoup deployments expose a REST API for room management, participant listing, and media routing configuration. Add an HTTP monitor for the API root or a dedicated status path:

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the URL: https://mediasoup.yourdomain.com/api/status (or your actual API health path).
3. Set Check interval to 2 minutes.
4. Set Expected HTTP status to 200.
5. Click Save.

If your API and signaling server are the same Node.js process, this monitor overlaps with the /health check — keep both, since they test different code paths and different paths through your server.

Step 5: SSL Certificate Expiry Alerts

Mediasoup's WSS signaling and HTTPS API both depend on TLS certificates. An expired certificate causes WebRTC clients to fail the initial WebSocket handshake, preventing any new session creation.

Monitor the HTTPS certificate

1. Click Add Monitor → SSL Certificate.
2. Enter hostname: mediasoup.yourdomain.com.
3. Set Alert threshold to 14 days before expiry.
4. Click Save.

Monitor the WSS certificate (if on a different port)

If your WebSocket signaling runs on a dedicated port with a different certificate:

1. Click Add Monitor → SSL Certificate.
2. Enter hostname: mediasoup.yourdomain.com with port 4443.
3. Set Alert threshold to 14 days before expiry.
4. Click Save.

Mediasoup's internal DTLS certificates (used for media encryption between the SFU and WebRTC clients) are generated and rotated automatically by the library — these do not require external monitoring.

Step 6: Heartbeat Monitor for Worker Process Availability

The /health endpoint checks whether workers are alive at the time of polling, but a worker can crash and be restarted between polls without triggering a Vigilmon alert. A heartbeat monitor provides continuous coverage: the Node.js application sends a ping to Vigilmon from within the worker management loop, so any gap in pings signals a problem.

Create the heartbeat monitor

1. In Vigilmon, click Add Monitor → Heartbeat.
2. Name it Mediasoup Worker Health.
3. Set Expected interval to 5 minutes.
4. Copy the heartbeat URL: https://vigilmon.online/api/heartbeat/YOUR_TOKEN

Send the heartbeat from your application

// server.js
import { setInterval } from 'timers';

const VIGILMON_HB_URL = 'https://vigilmon.online/api/heartbeat/YOUR_TOKEN';

function startHeartbeat() {
  setInterval(async () => {
    const aliveWorkers = workers.filter(w => !w.closed);

    if (aliveWorkers.length > 0) {
      try {
        await fetch(VIGILMON_HB_URL);
      } catch (err) {
        console.warn('Vigilmon heartbeat failed:', err.message);
      }
    } else {
      console.error('All Mediasoup workers dead — skipping heartbeat ping');
    }
  }, 5 * 60 * 1000); // every 5 minutes
}

await startWorkers();
startHeartbeat();
app.listen(3000);

Replace YOUR_TOKEN with your Vigilmon heartbeat token. The heartbeat is only sent when at least one worker is alive — if all workers die and stay dead (e.g., a crash loop that exhausts retries), Vigilmon alerts you after the expected interval passes without a ping.

Summary

Your Mediasoup deployment now has five layers of monitoring:

1. /health endpoint — checks active worker count and returns 503 if all workers are dead, polled every 60 seconds.
2. TCP WebSocket port — verifies the signaling channel is accepting connections for new WebRTC sessions.
3. HTTPS API monitor — confirms the REST management API is reachable and returning valid responses.
4. SSL certificates — alerts you 14 days before any HTTPS or WSS certificate expires.
5. Heartbeat — confirms the Node.js process is alive and has at least one healthy worker; Vigilmon alerts if pings stop for more than 5 minutes.

Vigilmon handles check scheduling, multi-region polling, alert routing, and uptime history. You get notified within 60 seconds of any failure — whether it's a crashed worker pool, a dropped WebSocket port binding, or a TLS certificate that silently expired and started rejecting all new client connections.

Monitor your Mediasoup infrastructure free at vigilmon.online

#mediasoup #webrtc #nodejs #monitoring #videoconferencing