Monitoring ThingsBoard with Vigilmon

ThingsBoard is an open-source IoT platform that handles device management, telemetry ingestion, rule engine processing, and data visualization — all self-hosted. When you run it yourself, there's no managed SLA catching failures: a crashed MQTT broker silently drops device messages, a stalled rule engine stops triggering automation, and a full Cassandra disk quietly kills time-series writes. Vigilmon gives you the monitoring layer ThingsBoard lacks out of the box, watching every critical service so you know before your devices do.

What You'll Set Up

• HTTP availability monitor for the ThingsBoard web interface
• MQTT broker health and connection count monitoring via TCP
• CoAP server status check
• Rule engine and telemetry pipeline health via API endpoint
• Time-series storage backend (Cassandra/PostgreSQL/TimescaleDB) connectivity
• WebSocket live data stream service health
• REST API integration service availability
• Scheduled analytics job heartbeat monitoring

Prerequisites

• ThingsBoard CE or PE installed (Docker, DEB package, or source)
• ThingsBoard accessible on ports 9090 (HTTP), 1883 (MQTT), 5683 (CoAP), 7070 (RPC)
• A free Vigilmon account

Step 1: Monitor the ThingsBoard Web Interface

The web UI running on port 9090 is the gateway to the entire platform. If this goes down, no dashboards, no device management, no API access.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your ThingsBoard URL: http://your-server:9090 (or https://thingsboard.yourdomain.com if behind a reverse proxy).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

For a richer health signal, ThingsBoard exposes a dedicated health endpoint:

http://your-server:9090/api/v1/health

Use this instead of the root URL — it verifies internal service readiness, not just the nginx proxy response.

Step 2: Monitor the MQTT Broker (TCP Port 1883)

IoT devices send telemetry over MQTT. A broken MQTT listener means devices can connect but data never arrives.

1. Click Add Monitor → TCP Port.
2. Enter your ThingsBoard host and port 1883.
3. Set Check interval to 2 minutes.
4. Click Save.

To verify MQTT is actually processing messages (not just accepting TCP connections), add a script-level check using the Mosquitto client:

# Install mosquitto-clients on your monitoring host
mosquitto_pub -h your-server -p 1883 -t "v1/devices/me/telemetry" \
  -u "YOUR_DEVICE_TOKEN" -m '{"health":1}'
echo "Exit: $?"

Wrap this in a cron job that pings a Vigilmon heartbeat on success:

#!/bin/bash
result=$(mosquitto_pub -h your-server -p 1883 -t "v1/devices/me/telemetry" \
  -u "YOUR_DEVICE_TOKEN" -m '{"health":1}' 2>&1)
if [ $? -eq 0 ]; then
  curl -s https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_ID
fi

Step 3: Monitor CoAP Server (Port 5683)

Constrained devices (Arduino, ESP8266, low-power sensors) use CoAP on port 5683. Vigilmon's TCP monitor can verify the UDP port is responding:

1. Click Add Monitor → TCP Port.
2. Enter host and port 5683.
3. Set interval to 5 minutes.

For active CoAP verification, use coap-client:

coap-client -m get "coap://your-server:5683/api/v1/YOUR_TOKEN/telemetry"

Add this to a heartbeat script identical to the MQTT example above.

Step 4: Monitor the REST API and Rule Engine Health

ThingsBoard's rule engine processes every device event. A stalled rule chain causes automation to silently stop. Monitor it via the admin health API:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-server:9090/api/v1/health
3. Set Expected response body contains to "status":"UP".
4. Set Check interval to 1 minute.

To verify rule engine specifically, query the rule chain stats endpoint (requires JWT auth):

#!/bin/bash
TOKEN=$(curl -s -X POST http://your-server:9090/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"tenant@thingsboard.org","password":"YOUR_PASSWORD"}' \
  | jq -r '.token')

STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "X-Authorization: Bearer $TOKEN" \
  http://your-server:9090/api/ruleChains?pageSize=1\&page=0)

if [ "$STATUS" = "200" ]; then
  curl -s https://vigilmon.online/heartbeat/RULE_ENGINE_HEARTBEAT_ID
fi

Run this every 5 minutes via cron.

Step 5: Monitor Time-Series Storage Backend

ThingsBoard stores device telemetry in Cassandra, PostgreSQL, or TimescaleDB depending on your configuration. A storage outage means no historical data — devices appear to work but nothing is recorded.

PostgreSQL / TimescaleDB

#!/bin/bash
pg_isready -h localhost -p 5432 -U thingsboard -d thingsboard
if [ $? -eq 0 ]; then
  curl -s https://vigilmon.online/heartbeat/DB_HEARTBEAT_ID
fi

Cassandra

#!/bin/bash
nodetool status | grep -q "^UN"
if [ $? -eq 0 ]; then
  curl -s https://vigilmon.online/heartbeat/CASSANDRA_HEARTBEAT_ID
fi

Add these as cron heartbeat monitors in Vigilmon:

1. Click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 5 minutes.
3. Copy the heartbeat URL and paste it into your check script.
4. Schedule the script with cron: */5 * * * * /opt/checks/db-health.sh

Step 6: Monitor WebSocket Service

ThingsBoard dashboards use WebSocket connections for live telemetry updates. If the WebSocket service fails, dashboards freeze silently.

Add a TCP monitor for the WebSocket port (usually same as HTTP, port 9090, but verify your config):

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-server:9090/api/ws/plugins/telemetry
3. Set Expected HTTP status to 101 (Switching Protocols) or 400 (if the server rejects non-WS HTTP requests — this still confirms the endpoint is alive).

Alternatively, use a WebSocket health probe script:

import websocket
import sys

try:
    ws = websocket.create_connection("ws://your-server:9090/api/ws/plugins/telemetry",
                                     timeout=5)
    ws.close()
    import urllib.request
    urllib.request.urlopen("https://vigilmon.online/heartbeat/WS_HEARTBEAT_ID")
except Exception as e:
    print(f"WebSocket check failed: {e}", file=sys.stderr)
    sys.exit(1)

Step 7: Monitor Integration and RPC Services

ThingsBoard integrates with external systems (REST API, OPC-UA, third-party MQTT) through its Integration service. RPC calls from the cloud to devices go through port 7070.

Monitor the RPC port:

1. Click Add Monitor → TCP Port.
2. Enter host and port 7070.
3. Set interval to 2 minutes.

For the Integration service, add an HTTP check against the integration health endpoint if your ThingsBoard version exposes one, or use the main /api/v1/health check from Step 4 — it reflects overall platform health including integrations.

Step 8: Heartbeat for Scheduled Analytics Jobs

ThingsBoard can run scheduled report generation and analytics jobs. These run silently in the background — if they stop, nobody notices until a report is missing.

Add a cron heartbeat monitor in Vigilmon and instrument your job:

For a ThingsBoard scheduled analytics task that runs nightly:

#!/bin/bash
# /opt/thingsboard/analytics-job.sh
python3 /opt/analytics/generate_report.py

if [ $? -eq 0 ]; then
  curl -s https://vigilmon.online/heartbeat/ANALYTICS_HEARTBEAT_ID
fi

Set the Vigilmon heartbeat interval to 25 hours (slightly longer than daily) so a missed job triggers an alert within one day.

Step 9: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and connect Slack, email, PagerDuty, or a webhook.
2. Set Consecutive failures before alert to 2 for the HTTP and TCP monitors — ThingsBoard services can take a few seconds to respond under load.
3. Tag monitors by severity: create groups for critical (MQTT, database) and warning (WebSocket, analytics jobs).

For deployments and maintenance, suppress false alerts:

# Silence alerts during ThingsBoard upgrade (15 minutes)
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "MONITOR_ID", "duration_minutes": 15}'

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP | :9090/api/v1/health | Web UI and platform down | | TCP | :1883 | MQTT broker crash | | TCP | :5683 | CoAP listener down | | TCP | :7070 | RPC service failure | | Heartbeat | MQTT probe script | Silent MQTT message drop | | Heartbeat | Rule engine API check | Rule chain stall | | Heartbeat | DB health check | Storage backend failure | | Heartbeat | WebSocket probe | Live dashboard failure | | Heartbeat | Analytics job | Missed scheduled report |

ThingsBoard handles the hard work of IoT data at scale — but self-hosting means you own the reliability. With Vigilmon watching every layer from the MQTT broker to the time-series database, you catch outages before devices start silently dropping data into the void.