tutorial

Uptime monitoring for Memphis message broker

Memphis is the modern open-source message broker built for developers who want Kafka-level throughput without the operational complexity. It handles event st...

Memphis is the modern open-source message broker built for developers who want Kafka-level throughput without the operational complexity. It handles event streaming, async task queues, and message fan-out across your services. When Memphis goes down, your producers start dropping messages, your consumers stall, and the data pipeline you depend on falls silent — often without a visible error in your application logs.

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

  • Monitoring the Memphis HTTP management API
  • TCP port monitoring for the broker
  • Monitoring the REST endpoint health
  • Heartbeat monitoring for Memphis stations and consumers
  • Webhook alerts for DOWN/UP events

Prerequisites

  • Memphis running (Docker, Kubernetes, or bare metal)
  • A free account at vigilmon.online

Part 1: The Memphis management API

Memphis exposes an HTTP management API and a web UI on port 9000. This is the primary interface for monitoring broker health, station status, and consumer group lag.

Start Memphis

# docker-compose.yml
version: "3.8"

services:
  memphis:
    image: memphisos/memphis:latest
    environment:
      DOCKER_ENV: "true"
      ROOT_PASSWORD: "memphis"
    ports:
      - "6666:6666"   # Memphis client connections
      - "9000:9000"   # Management HTTP API / UI
      - "7770:7770"   # REST gateway
    volumes:
      - memphis_data:/var/lib/memphis

volumes:
  memphis_data:

docker compose up -d

# Verify Memphis is running
curl http://localhost:9000/health

The health endpoint

Memphis exposes /health on the management API port:

curl http://localhost:9000/health

Expected response:

{
  "alive": true
}

HTTP 200 with "alive": true confirms the Memphis management layer is operational.

Verify the REST gateway

Memphis also provides a REST gateway for HTTP-based producers and consumers (default port 7770):

curl http://localhost:7770/
# Expected: HTTP 200 or 404 (confirming the REST gateway process is running)

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://memphis.example.com/health
  4. Set interval to 1 minute.
  5. Add a keyword check: must contain "alive":true.
  6. Click Save.

Monitor the REST gateway

The REST gateway is used by producers and consumers that connect over HTTP rather than the native Memphis protocol. Monitor it separately:

  1. In Vigilmon, click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: https://memphis-rest.example.com/
  4. Set interval to 1 minute.
  5. Set expected HTTP status to any non-5xx.
  6. Click Save.

Monitor the management UI

The management UI at https://memphis.example.com gives your team visibility into stations and consumer lag. If the UI goes down, your operations team loses observability:

  1. In Vigilmon, click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: https://memphis.example.com
  4. Set interval to 1 minute.
  5. Add a keyword check: Memphis.
  6. Click Save.

Part 3: TCP port monitoring for broker availability

The Memphis broker port (6666) is the connection point for all native Memphis clients — producers and consumers. HTTP API availability does not guarantee that the broker port is open. Monitor it independently:

  1. In Vigilmon, click Add Monitor.
  2. Choose TCP monitor.
  3. Enter host: memphis.example.com and port: 6666.
  4. Set interval to 1 minute.
  5. Click Save.

| Monitor name | Host | Port | Purpose | |---|---|---|---| | Memphis broker port | memphis.example.com | 6666 | Native client connections | | Memphis management API | memphis.example.com | 9000 | HTTP management + UI | | Memphis REST gateway | memphis.example.com | 7770 | REST-based producers/consumers |

A TCP check on port 6666 catches broker failures that are invisible at the HTTP layer — for example, a crashed NATS-based backend that Memphis sits on top of.

Part 4: Heartbeat monitoring for Memphis stations and consumers

The most damaging class of Memphis failure is not a crash — it is a silent stall. A consumer group stops processing messages. A producer stops publishing. The broker is healthy, but data is not flowing. Heartbeat monitoring catches this.

Set up a Vigilmon heartbeat monitor

  1. In Vigilmon, click Add Monitor.
  2. Choose Heartbeat monitor.
  3. Name it: Memphis order-events consumer.
  4. Set interval to match your expected processing cadence (e.g., 5 minutes).
  5. Copy the generated heartbeat URL.

Ping the heartbeat from your consumer

# Python consumer with heartbeat monitoring
import asyncio
import httpx
from memphis import Memphis, Headers, MemphisError

MEMPHIS_HOST = "memphis.example.com"
MEMPHIS_USERNAME = "consumer-user"
MEMPHIS_PASSWORD = "consumer-password"
VIGILMON_HEARTBEAT_URL = "https://vigilmon.online/heartbeat/your-heartbeat-id"

async def main():
    memphis = Memphis()
    await memphis.connect(
        host=MEMPHIS_HOST,
        username=MEMPHIS_USERNAME,
        password=MEMPHIS_PASSWORD,
    )

    consumer = await memphis.consumer(
        station_name="order-events",
        consumer_name="order-processor",
        consumer_group="order-service",
    )

    async def msg_handler(msgs, error, context):
        if error:
            print(f"Consumer error: {error}")
            return

        for msg in msgs:
            await process_order(msg.get_data())
            await msg.ack()

        # Signal successful processing to Vigilmon
        async with httpx.AsyncClient() as client:
            await client.get(VIGILMON_HEARTBEAT_URL, timeout=5)

    consumer.consume(msg_handler)
    await asyncio.sleep(float("inf"))

asyncio.run(main())

// TypeScript consumer with heartbeat monitoring
import { Memphis } from 'memphis-dev';
import axios from 'axios';

const VIGILMON_HEARTBEAT_URL = process.env.VIGILMON_HEARTBEAT_URL!;

async function startConsumer() {
  const memphis = await Memphis.connect({
    host: process.env.MEMPHIS_HOST!,
    username: process.env.MEMPHIS_USERNAME!,
    password: process.env.MEMPHIS_PASSWORD!,
  });

  const consumer = await memphis.consumer({
    stationName: 'order-events',
    consumerName: 'order-processor',
    consumerGroup: 'order-service',
  });

  consumer.on('message', async (msg) => {
    const order = JSON.parse(msg.getData().toString());
    await processOrder(order);
    msg.ack();

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

  consumer.on('error', (err) => {
    console.error('Consumer error:', err);
    // Heartbeat NOT pinged — Vigilmon will alert after interval expires
  });
}

startConsumer();

Monitor a producer station

For producer-side monitoring, ping the heartbeat after successful message publication:

# Python producer with heartbeat monitoring
import asyncio
import httpx
import json
from memphis import Memphis

VIGILMON_HEARTBEAT_URL = "https://vigilmon.online/heartbeat/your-producer-heartbeat-id"

async def publish_batch():
    memphis = Memphis()
    await memphis.connect(
        host="memphis.example.com",
        username="producer-user",
        password="producer-password",
    )

    producer = await memphis.producer(
        station_name="analytics-events",
        producer_name="analytics-producer",
    )

    events = await fetch_pending_events()
    for event in events:
        await producer.produce(
            message=json.dumps(event).encode(),
        )

    await memphis.close()

    # Signal successful batch to Vigilmon
    async with httpx.AsyncClient() as client:
        await client.get(VIGILMON_HEARTBEAT_URL, timeout=5)

asyncio.run(publish_batch())

If Vigilmon does not receive a ping within the interval, it alerts you — even though Memphis itself is still healthy and the broker port is responding.

Part 5: SSL certificate monitoring

If Memphis is exposed over HTTPS (directly or behind a reverse proxy), certificate expiry breaks access to the management API, the UI, and potentially the REST gateway.

# Nginx reverse proxy for Memphis management API
server {
    listen 443 ssl;
    server_name memphis.example.com;

    ssl_certificate /etc/letsencrypt/live/memphis.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/memphis.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Add SSL monitoring in Vigilmon

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

Add SSL monitors for all domains in your Memphis deployment, including any separate REST gateway domains.

Part 6: Webhook alerts

Configure Vigilmon webhooks so your team is notified immediately when Memphis goes down — message pipeline failures compound quickly as queues grow:

// 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] Memphis DOWN', {
      monitor: monitor_name,
      url,
      code: response_code,
      at: checked_at,
    });
    // Message broker outages affect every async service — escalate immediately
    notifyOnCall({
      title: `Memphis broker DOWN: ${monitor_name}`,
      url,
      severity: 'high',
    });
  } else if (status === 'up') {
    console.info('[VIGILMON] Memphis recovered', {
      monitor: monitor_name,
      at: checked_at,
    });
  }

  res.sendStatus(204);
});

Vigilmon sends this payload on DOWN and UP transitions:

{
  "monitor_id": "mon_abc123",
  "monitor_name": "Memphis broker port",
  "status": "down",
  "url": "memphis.example.com:6666",
  "checked_at": "2026-06-30T08:01:00Z",
  "response_code": null,
  "response_time_ms": 5000
}

Part 7: Kubernetes deployment

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: memphis
  namespace: memphis
spec:
  serviceName: memphis
  replicas: 1
  selector:
    matchLabels:
      app: memphis
  template:
    metadata:
      labels:
        app: memphis
    spec:
      containers:
        - name: memphis
          image: memphisos/memphis:latest
          env:
            - name: DOCKER_ENV
              value: "true"
          ports:
            - containerPort: 6666
            - containerPort: 9000
            - containerPort: 7770
          livenessProbe:
            httpGet:
              path: /health
              port: 9000
            initialDelaySeconds: 30
            periodSeconds: 30
          readinessProbe:
            httpGet:
              path: /health
              port: 9000
            initialDelaySeconds: 15
            periodSeconds: 10
          volumeMounts:
            - name: memphis-data
              mountPath: /var/lib/memphis
  volumeClaimTemplates:
    - metadata:
        name: memphis-data
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 20Gi

Expose the management API externally for Vigilmon to poll:

apiVersion: v1
kind: Service
metadata:
  name: memphis-external
  namespace: memphis
spec:
  type: LoadBalancer
  selector:
    app: memphis
  ports:
    - name: management
      port: 9000
      targetPort: 9000

Summary

Your Memphis deployment now has five layers of monitoring:

  1. /health HTTP monitor — confirms the Memphis management API is alive, polled every 60 seconds with a keyword check on "alive":true.
  2. TCP port monitor on 6666 — verifies the broker port is reachable independently of the management layer, catching backend failures invisible to HTTP checks.
  3. REST gateway monitor — ensures HTTP-based producers and consumers can reach Memphis.
  4. Heartbeat monitors — one per critical station/consumer, catching silent stalls where Memphis is healthy but data is not flowing.
  5. SSL monitor — alerts you 14 days before certificate expiry on the management API domain.

Vigilmon handles check scheduling, multi-region polling, alert routing, and uptime history — your team is notified within 60 seconds of any Memphis failure, before message queues grow unbounded.

Monitor your Memphis message broker free at vigilmon.online

#memphis #messagebroker #eventstreaming #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