tutorial

Monitoring Eclipse Hono with Vigilmon

Eclipse Hono is an open source IoT device connectivity middleware supporting MQTT, AMQP, HTTP, and CoAP. Here's how to monitor Hono protocol adapters, device registry, messaging network, authentication, and consumer lag with Vigilmon.

Eclipse Hono is a Bosch- and Eurotech-backed Eclipse IoT project that connects millions of heterogeneous IoT devices — using MQTT, AMQP, HTTP, CoAP, and LoRaWAN — to a unified scalable messaging backend. When Hono's MQTT adapter crashes, the device registry becomes unavailable, or the AMQP messaging backbone stalls, device telemetry stops flowing to business applications with no visible indication. Vigilmon gives you per-adapter health visibility, messaging network monitoring, and consumer lag alerting across every layer of your Hono deployment.

What You'll Set Up

  • Hono MQTT adapter health monitor
  • Hono HTTP adapter health monitor
  • Hono AMQP adapter health monitor
  • Device registry availability heartbeat
  • AMQP messaging network (Qpid/Artemis) health monitor
  • Downstream application consumer lag heartbeat
  • Command and Control delivery rate heartbeat
  • Authentication success rate heartbeat
  • Message throughput heartbeat
  • Tenant management health heartbeat

Prerequisites

  • Eclipse Hono deployed via Docker Compose or Helm on Kubernetes
  • MQTT adapter on port 8883, HTTP adapter on port 8080/8443, AMQP adapter on port 5671
  • Device Registry REST API accessible
  • Qpid Dispatch Router or Apache ActiveMQ Artemis management API accessible
  • A free Vigilmon account

Step 1: Monitor Hono MQTT Adapter Health

Most IoT devices connect to Hono via MQTT. When the MQTT adapter crashes, every MQTT-connected device loses its telemetry path immediately — there's no reconnect because the port becomes unreachable.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to TCP Port.
  3. Host: your-hono-host.
  4. Port: 8883 (MQTT over TLS; use 1883 for plaintext in development).
  5. Check interval: 1 minute.
  6. Click Save.

For a richer health check that verifies the adapter is processing connections (not just listening), use the Hono health check endpoint if exposed:

  1. Add a second monitor with Type HTTP / HTTPS.
  2. URL: http://your-hono-host:8088/liveness (Hono Quarkus-based adapters expose /liveness and /readiness).
  3. Expected HTTP status: 204.
  4. Click Save.

Step 2: Monitor Hono HTTP Adapter Health

HTTP adapter availability is critical for devices that post telemetry via REST. A failed HTTP adapter silently drops all HTTP-based device data.

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-hono-host:8080 (or https://your-hono-host:8443).
  3. Check interval: 1 minute.
  4. Expected HTTP status: 200 or 404 (Hono returns 404 on the root path but the adapter is alive).
  5. Click Save.

For Quarkus-based Hono:

  1. Add a HTTP / HTTPS monitor to http://your-hono-host:8088/readiness.
  2. Expected HTTP status: 204.
  3. Click Save.

Step 3: Monitor Hono AMQP Adapter Health

Industrial devices using native AMQP 1.0 rely on the AMQP adapter. Deploy a TCP port monitor:

  1. Click Add Monitor → TCP Port.
  2. Host: your-hono-host.
  3. Port: 5671 (AMQP over TLS) or 5672 (plaintext).
  4. Check interval: 1 minute.
  5. Click Save.

Step 4: Monitor Device Registry Health

Protocol adapters authenticate every incoming device connection against the Device Registry. When the registry is unavailable, adapters reject all device connections — even valid ones with correct credentials.

#!/bin/bash
# /opt/monitoring/check-hono-registry.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
REGISTRY_HOST="your-hono-host"
REGISTRY_PORT="28080"  # Device Registry HTTP management port

# Query device registry health — list tenants endpoint
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  "http://${REGISTRY_HOST}:${REGISTRY_PORT}/v1/tenants?page_size=1" \
  --max-time 10)

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

In Vigilmon:

  1. Click Add Monitor → Cron Heartbeat.
  2. Name: Hono Device Registry.
  3. Expected interval: 2 minutes.
  4. Grace period: 5 minutes.
  5. Schedule: */2 * * * * /opt/monitoring/check-hono-registry.sh.
  6. Click Save.

Step 5: Monitor AMQP Messaging Network Health

Hono's backbone — Qpid Dispatch Router or Apache ActiveMQ Artemis — routes all device messages from protocol adapters to downstream business applications. A failure here stops all device data from reaching any application, regardless of which adapter the device uses.

For Apache ActiveMQ Artemis:

#!/bin/bash
# /opt/monitoring/check-hono-artemis.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
ARTEMIS_HOST="your-artemis-host"
ARTEMIS_USER="artemis"
ARTEMIS_PASS="artemis"

HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -u "${ARTEMIS_USER}:${ARTEMIS_PASS}" \
  "http://${ARTEMIS_HOST}:8161/console/jolokia/read/org.apache.activemq.artemis:broker=\"artemis\"/Started" \
  --max-time 10)

if [ "$HTTP_STATUS" = "200" ]; then
  STARTED=$(curl -s -u "${ARTEMIS_USER}:${ARTEMIS_PASS}" \
    "http://${ARTEMIS_HOST}:8161/console/jolokia/read/org.apache.activemq.artemis:broker=\"artemis\"/Started" \
    --max-time 10 | grep -o '"value":true')
  if [ "$STARTED" = '"value":true' ]; then
    curl -s -X POST "$HEARTBEAT_URL" > /dev/null
  fi
fi

For Qpid Dispatch Router, check its management API or TCP port:

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

if nc -z your-qpid-host 5672 2>/dev/null; then
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null
fi

Set the expected interval to 2 minutes with a 3-minute grace period.

Step 6: Monitor Downstream Consumer Lag

Business applications consume device telemetry from Hono's AMQP messaging network. When applications fall behind — due to processing slowdowns or consumer crashes — the queue depth grows and eventually causes memory pressure on the broker.

#!/bin/bash
# /opt/monitoring/check-hono-consumer-lag.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
ARTEMIS_HOST="your-artemis-host"
ARTEMIS_USER="artemis"
ARTEMIS_PASS="artemis"
MAX_QUEUE_DEPTH=10000  # alert if consumer is >10k messages behind

# Check message count on the telemetry queue for your tenant
QUEUE_DEPTH=$(curl -s -u "${ARTEMIS_USER}:${ARTEMIS_PASS}" \
  "http://${ARTEMIS_HOST}:8161/console/jolokia/read/org.apache.activemq.artemis:broker=\"artemis\",component=addresses,address=\"telemetry\\/YOUR_TENANT_ID\",subcomponent=queues,routing-type=\"anycast\",queue=\"telemetry\\/YOUR_TENANT_ID\"/MessageCount" \
  --max-time 10 | grep -o '"value":[0-9]*' | head -1 | cut -d: -f2)

QUEUE_DEPTH="${QUEUE_DEPTH:-0}"
if [ "$QUEUE_DEPTH" -lt "$MAX_QUEUE_DEPTH" ]; then
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null
fi

Set the expected interval to 5 minutes with a 10-minute grace period.

Step 7: Monitor Command and Control Delivery

Hono enables cloud applications to send commands to specific devices through protocol adapters. Failed command delivery means devices aren't receiving control instructions — a silent failure in actuator-heavy IoT systems.

#!/bin/bash
# /opt/monitoring/check-hono-c2d.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
HONO_HOST="your-hono-host"
TENANT_ID="your-tenant-id"
DEVICE_ID="your-probe-device-id"
AUTH_ID="your-auth-id"
PASSWORD="your-device-password"

# Send a one-way command to a known probe device via HTTP adapter
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -X PUT \
  -u "${AUTH_ID}@${TENANT_ID}:${PASSWORD}" \
  -H "Content-Type: application/json" \
  -d '{"operation":"ping"}' \
  "http://${HONO_HOST}:8080/command/${TENANT_ID}/${DEVICE_ID}/probe" \
  --max-time 15)

# 202 = command accepted for delivery; 503 = adapter overloaded
if [ "$HTTP_STATUS" = "202" ]; then
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null
fi

Set the expected interval to 5 minutes with a 10-minute grace period.

Step 8: Monitor Authentication Success Rate

Protocol adapters authenticate every incoming device connection against the Device Registry. A spike in authentication failures — caused by credential rotation errors, registry unavailability, or misconfigured devices — causes mass device disconnection.

#!/bin/bash
# /opt/monitoring/check-hono-auth.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
HONO_HOST="your-hono-host"
TENANT_ID="your-tenant-id"

# Attempt authentication with a known-good probe credential
# This exercises the full auth path: adapter → device registry → credential lookup
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -u "probe-device@${TENANT_ID}:probe-password" \
  -H "Content-Type: application/json" \
  -d '{"temperature": 22.5}' \
  "http://${HONO_HOST}:8080/telemetry" \
  --max-time 15)

# 202 = authenticated and telemetry accepted
if [ "$HTTP_STATUS" = "202" ]; then
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null
fi

Set the expected interval to 2 minutes with a 5-minute grace period.

Step 9: Monitor Message Throughput

A significant drop in messages per second through Hono indicates upstream device connectivity loss, adapter overload, or downstream consumer starvation. Track throughput via the Artemis message rate metric:

#!/bin/bash
# /opt/monitoring/check-hono-throughput.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
ARTEMIS_HOST="your-artemis-host"
ARTEMIS_USER="artemis"
ARTEMIS_PASS="artemis"
MIN_MESSAGES_PER_SEC=1  # alert if no messages flowing (adapt to your fleet)

RATE=$(curl -s -u "${ARTEMIS_USER}:${ARTEMIS_PASS}" \
  "http://${ARTEMIS_HOST}:8161/console/jolokia/read/org.apache.activemq.artemis:broker=\"artemis\"/MessagesAdded" \
  --max-time 10 | grep -o '"value":[0-9]*' | head -1 | cut -d: -f2)

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

Set the expected interval to 5 minutes with a 10-minute grace period. Tune the threshold based on your fleet's expected idle throughput.

Step 10: Configure Alerting

Apply alert channels to all Hono monitors:

  1. Go to Alerts → Add Alert Channel → choose Email, Slack, PagerDuty, or Webhook.
  2. Apply the channel to all Hono monitors.

Recommended thresholds:

| Monitor | Alert After | Severity | |---|---|---| | MQTT adapter TCP port | 1 missed check | Critical | | HTTP adapter | 2 missed checks | High | | AMQP adapter TCP port | 1 missed check | High | | Device registry | 1 missed check | Critical | | AMQP messaging network | 1 missed check | Critical | | Consumer queue lag | 1 missed check | High | | Command and control delivery | 2 missed checks | High | | Authentication success | 1 missed check | Critical | | Message throughput | 2 missed checks | High |

Conclusion

Eclipse Hono sits at the protocol boundary between heterogeneous IoT devices and your business applications. When any adapter, the device registry, or the AMQP messaging backbone degrades, device data stops flowing and cloud-to-device commands fail silently. With Vigilmon monitoring the full stack — per-adapter TCP availability, authentication paths, consumer lag, and messaging network health — you get immediate alerts on every failure mode before devices lose connectivity or telemetry pipelines go dark.

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

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