Monitoring Magistrala with Vigilmon

Magistrala (formerly Mainflux, rebranded in 2023) is a cloud-native, open source IoT messaging and device management platform written in Go. It provides the complete IoT infrastructure backbone: device identity management (Things), protocol adapters (MQTT, HTTP, CoAP, WebSocket), an internal NATS message broker, and time-series database writers (TimescaleDB, InfluxDB, Cassandra). When you self-host Magistrala, you're running a microservice mesh — any one service crashing silently degrades device connectivity or message persistence without a visible error to end users or devices. Vigilmon gives you end-to-end monitoring across the full Magistrala service stack so you can detect failures before devices lose connectivity or data is lost.

What You'll Set Up

• Things service API health monitor
• MQTT adapter port monitor (1883 / 8883)
• HTTP adapter health monitor
• NATS message broker heartbeat
• Message writer health heartbeat (TimescaleDB / InfluxDB)
• Device authorization service monitor
• Message ingestion throughput heartbeat
• TLS certificate expiry monitor for all adapters
• Channels service health monitor

Prerequisites

• Magistrala deployed via Docker Compose or Kubernetes (latest release)
• Things service accessible on its HTTP port (default: 9000)
• MQTT adapter accessible on port 1883 (MQTT) and/or 8883 (MQTT over TLS)
• HTTP adapter accessible on port 8008
• NATS running as internal message broker (default port 4222)
• A free Vigilmon account

Step 1: Monitor the Things Service

The Things service manages all IoT device identities and credentials. If it crashes, new devices can't connect and existing device credential lookups fail, causing authorization errors across all adapters.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. URL: http://magistrala.yourdomain.com:9000/health (or the Magistrala Things service health endpoint at your deployment URL).
4. Check interval: 1 minute.
5. Expected HTTP status: 200.
6. Under Keyword check, enter pass (Magistrala health responses return {"status":"pass"}).
7. Click Save.

If you expose Magistrala via a reverse proxy at a single domain:

1. URL: https://magistrala.yourdomain.com/things/health.
2. Enable Monitor SSL certificate → set expiry alert to 21 days.
3. Click Save.

Alert recommendation: Alert after 1 missed check — Things service unavailability means zero new device connections succeed.

Step 2: Monitor the MQTT Adapter

The MQTT adapter is how the majority of IoT devices connect to Magistrala. Monitor both the plain MQTT port and the TLS MQTT port independently — some devices use only one.

Plain MQTT (port 1883):

1. Click Add Monitor → TCP Port.
2. Host: magistrala.yourdomain.com.
3. Port: 1883.
4. Check interval: 1 minute.
5. Click Save.

MQTT over TLS (port 8883):

1. Click Add Monitor → TCP Port.
2. Host: magistrala.yourdomain.com.
3. Port: 8883.
4. Check interval: 1 minute.
5. Click Save.

For a deeper MQTT adapter health check that verifies the adapter process (not just the port), add an HTTP monitor on the adapter's health endpoint if your deployment exposes one:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://magistrala.yourdomain.com:8883/health (adapt to your deployment).
3. Expected HTTP status: 200.
4. Click Save.

Alert recommendation: Alert on the first missed MQTT check — every device using MQTT is immediately affected.

Step 3: Monitor the HTTP Adapter

The HTTP adapter allows devices and services to publish messages via REST. Monitor its availability independently of the MQTT adapter.

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://magistrala.yourdomain.com:8008/health.
3. Check interval: 1 minute.
4. Expected HTTP status: 200.
5. Click Save.

To verify the HTTP adapter can actually process a publish request (not just serve the health endpoint), add a heartbeat probe that posts a test message:

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"

# Publish a test message to a monitoring channel via HTTP adapter
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -X POST http://magistrala.yourdomain.com:8008/channels/YOUR_MONITOR_CHANNEL_ID/messages \
  -H "Authorization: Thing YOUR_MONITOR_THING_SECRET" \
  -H "Content-Type: application/senml+json" \
  -d '[{"bn":"monitor/","n":"heartbeat","v":1}]')

if [ "$STATUS" = "202" ]; then
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null
fi

Schedule every 2 minutes. Magistrala returns HTTP 202 Accepted on successful message publish.

Step 4: Monitor the NATS Message Broker

Magistrala routes all inter-service messages through NATS (or optionally RabbitMQ). A NATS connectivity failure causes adapters to drop messages silently — devices connect successfully but their messages never reach the writers or subscribers.

1. Click Add Monitor → TCP Port.
2. Host: nats.yourdomain.com (or localhost if NATS is on the same host).
3. Port: 4222.
4. Check interval: 1 minute.
5. Click Save.

For an HTTP-based NATS health check using the NATS monitoring endpoint:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://nats.yourdomain.com:8222/healthz.
3. Expected HTTP status: 200.
4. Keyword check: ok.
5. Click Save.

Add a deeper publisher health heartbeat that confirms NATS subject routing works end-to-end:

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"

# Publish a test message to NATS and check it was accepted
nats pub magistrala.monitor.heartbeat "ping" \
  --server nats://nats.yourdomain.com:4222 2>/dev/null && \
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null

Step 5: Monitor Message Writer Health

The Magistrala message writer service consumes messages from NATS and persists them to your time-series database (TimescaleDB, InfluxDB, Cassandra, or MongoDB). If the writer fails, messages are lost permanently — devices keep publishing but nothing is stored.

Add a heartbeat that verifies the writer is consuming and the database is receiving inserts:

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"

# Query TimescaleDB for a recent message insert (within the last 5 minutes)
RECENT=$(psql -U magistrala -h timescaledb.yourdomain.com -d magistrala \
  -tAc "SELECT COUNT(*) FROM messages WHERE time > NOW() - INTERVAL '5 minutes';" 2>/dev/null)

if [ -n "$RECENT" ] && [ "$RECENT" -gt 0 ]; then
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null
fi

For InfluxDB:

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"

RECENT=$(curl -s "http://influxdb.yourdomain.com:8086/query" \
  --data-urlencode "db=magistrala" \
  --data-urlencode "q=SELECT COUNT(*) FROM messages WHERE time > now() - 5m" \
  | jq -r '.results[0].series[0].values[0][1] // 0')

if [ "$RECENT" -gt 0 ]; then
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null
fi

Set the Vigilmon heartbeat expected interval to 5 minutes with a 10-minute grace period. The grace period accounts for low-traffic periods where devices may genuinely not publish for several minutes.

Step 6: Monitor Device Authorization Health

Magistrala validates device credentials (Thing secret keys) for every message received by any adapter. If the auth service becomes slow or unavailable, devices receive 403 errors and messages are dropped even though devices are connected.

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://magistrala.yourdomain.com:8180/health (the auth service health endpoint — adjust port per your deployment).
3. Check interval: 1 minute.
4. Expected HTTP status: 200.
5. Click Save.

For a latency-sensitive auth probe, use a heartbeat that measures authorization round-trip time:

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
MAX_AUTH_MS=200  # 200ms SLO for authorization

START=$(date +%s%3N)
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -X POST http://magistrala.yourdomain.com:8180/identify \
  -H "Content-Type: application/json" \
  -d '{"token":"YOUR_MONITOR_THING_SECRET"}')
END=$(date +%s%3N)

ELAPSED=$((END - START))
if [ "$STATUS" = "200" ] && [ "$ELAPSED" -lt "$MAX_AUTH_MS" ]; then
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null
fi

Step 7: Monitor Message Ingestion Throughput

A significant drop in messages per second is an early indicator that devices are disconnecting, the MQTT adapter is overloaded, or the internal message broker is backpressuring. Monitor ingestion throughput via NATS monitoring stats:

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
MIN_MSGS_PER_SEC=10  # adjust to your baseline

# Get NATS message rate from the monitoring API
MSG_RATE=$(curl -s http://nats.yourdomain.com:8222/varz | jq -r '.in_msgs_per_sec // 0')

if (( $(echo "$MSG_RATE >= $MIN_MSGS_PER_SEC" | bc -l) )); then
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null
fi

Adjust MIN_MSGS_PER_SEC to 50% of your normal baseline throughput. Set the heartbeat expected interval to 5 minutes with a 15-minute grace period to absorb natural traffic lulls.

Step 8: Monitor the Channels Service

Channels are the logical message buses in Magistrala — Things subscribe and publish to Channels. If the Channels service fails, message routing breaks even when adapters and NATS are healthy.

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://magistrala.yourdomain.com:9000/channels (the Channels API endpoint, adjust per your deployment).
3. Expected HTTP status: 200 or 401 (401 confirms the API is responding and requiring auth correctly).
4. Check interval: 1 minute.
5. Click Save.

Step 9: Monitor TLS Certificate Health on All Adapters

Magistrala enforces TLS on all production adapters. An expired certificate immediately disconnects every device that uses TLS — a full-fleet outage. Monitor certificate expiry on each TLS-enabled adapter endpoint.

For the MQTT TLS port:

1. Click Add Monitor → HTTP / HTTPS (Vigilmon checks the certificate at any HTTPS/TLS endpoint).
2. URL: https://magistrala.yourdomain.com:8883 (or the FQDN your MQTT clients use).
3. Check interval: 1 day.
4. Enable Monitor SSL certificate → set expiry alert to 30 days.
5. Click Save.

Repeat for the HTTP adapter TLS endpoint and any other HTTPS-fronted service.

Alert recommendation: 30-day lead time gives you two renewal windows before expiry — don't shorten this for production IoT deployments where certificate rotation requires coordinated device updates.

Step 10: Configure Alerting

Set up a unified alert channel for all Magistrala monitors:

1. Go to Alerts → Add Alert Channel → choose Email, Slack, PagerDuty, or Webhook.
2. Apply the channel to every Magistrala monitor.

Recommended thresholds:

| Monitor | Alert After | Severity | |---|---|---| | Things service | 1 missed check | Critical | | MQTT adapter port 1883 | 1 missed check | Critical | | MQTT adapter port 8883 | 1 missed check | Critical | | NATS TCP port | 1 missed check | Critical | | Message writer heartbeat | 1 missed check | High | | HTTP adapter | 2 missed checks | High | | Auth service | 1 missed check | High | | Ingestion throughput | 1 missed check | Medium | | Channels service | 2 missed checks | High | | TLS certificate expiry | 30 days before | High |

Conclusion

Magistrala's microservice architecture distributes failure across Things, MQTT/HTTP adapters, NATS, auth, writers, and the Channels service — each can degrade independently and silently. With Vigilmon you get port checks on every adapter, HTTP health probes on every service, heartbeat-driven writer confirmation, ingestion throughput monitoring, and TLS certificate tracking — all feeding into a single alert channel. When any layer in your IoT messaging stack degrades, you know in minutes rather than hours.

Get started at vigilmon.online — free for up to 5 monitors.