tutorial

Monitoring Eclipse Hawkbit with Vigilmon

Eclipse Hawkbit is an open source IoT device software update management server. Here's how to monitor Hawkbit application health, DDI API, rollout progress, RabbitMQ connectivity, and target update failures with Vigilmon.

Eclipse Hawkbit is a Bosch-developed Eclipse IoT project that manages over-the-air (OTA) firmware and software updates across large fleets of IoT devices. When Hawkbit goes down — or when RabbitMQ loses connectivity, a rollout enters ERROR state, or the DDI API stops responding — devices stop receiving critical updates and engineers lose all visibility into deployment progress. Vigilmon gives you real-time alerts on every layer of your Hawkbit deployment, from the Spring Boot server itself to individual rollout failure rates.

What You'll Set Up

  • Hawkbit Spring Boot application health monitor
  • DDI API availability and device polling health heartbeat
  • Management API health heartbeat
  • RabbitMQ connectivity heartbeat
  • Rollout progress and error state monitor
  • Target update failure rate heartbeat
  • Download throughput monitor
  • Database connectivity heartbeat
  • Target registration rate heartbeat
  • Auto-assign rule health heartbeat

Prerequisites

  • Eclipse Hawkbit 0.3.x or later running via Docker or Kubernetes
  • Spring Boot Actuator enabled (default on Hawkbit)
  • Hawkbit Management API accessible (port 8080 by default)
  • MariaDB/MySQL and RabbitMQ accessible from the monitoring host
  • A free Vigilmon account

Step 1: Monitor Hawkbit Application Health

Hawkbit runs as a Spring Boot application and exposes a standard Actuator health endpoint at /actuator/health. A non-200 response or an unreachable port means the JVM has crashed or been OOM-killed, rendering all OTA management unavailable.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. URL: http://your-hawkbit-host:8080/actuator/health.
  4. Check interval: 1 minute.
  5. Expected HTTP status: 200.
  6. Under Keyword match, add "status":"UP" to verify the application reports healthy (not just that the port is open).
  7. Click Save.

If your Hawkbit instance is behind a reverse proxy with TLS, use the HTTPS URL and enable Monitor SSL certificate with a 21-day expiry alert.

Step 2: Monitor DDI API Health

IoT devices poll the Direct Device Integration (DDI) API to check for pending firmware updates and report installation status. If the DDI endpoint is unreachable, devices silently stop receiving update assignments — the fleet falls behind without any operator notification.

Deploy a heartbeat script on a host with access to the Hawkbit network:

#!/bin/bash
# /opt/monitoring/check-hawkbit-ddi.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
HAWKBIT_HOST="your-hawkbit-host"
DDI_PORT="8080"

# DDI API base endpoint — devices poll /{tenantId}/controller/v1/{controllerId}
# Use a test tenant/controller ID, or just check the base path returns 404 (not 5xx)
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  "http://${HAWKBIT_HOST}:${DDI_PORT}/DEFAULT/controller/v1/test-probe" \
  --max-time 10)

# 404 = endpoint exists, controller not found (expected for probe)
# 200 = controller found
# 5xx = server error
if [ "$HTTP_STATUS" = "200" ] || [ "$HTTP_STATUS" = "404" ]; then
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null
fi

In Vigilmon:

  1. Click Add Monitor → Cron Heartbeat.
  2. Name: Hawkbit DDI API.
  3. Expected interval: 2 minutes.
  4. Grace period: 5 minutes.
  5. Copy the heartbeat URL into the script.
  6. Schedule with cron: */2 * * * * /opt/monitoring/check-hawkbit-ddi.sh.
  7. Click Save.

Step 3: Monitor Management API Health

Operators manage rollouts, targets, and distribution sets through the Hawkbit Management REST API. If this API is down, rollout operations halt and engineers lose the ability to control ongoing deployments.

#!/bin/bash
# /opt/monitoring/check-hawkbit-mgmt.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
HAWKBIT_USER="admin"
HAWKBIT_PASS="admin"
HAWKBIT_HOST="your-hawkbit-host"

# Query the targets list — a basic Management API health probe
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -u "${HAWKBIT_USER}:${HAWKBIT_PASS}" \
  "http://${HAWKBIT_HOST}:8080/rest/v1/targets?limit=1" \
  --max-time 10)

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

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

Step 4: Monitor RabbitMQ Connectivity

Hawkbit uses RabbitMQ for asynchronous device event communication — device status updates, update confirmations, and cancellation notices all flow through the message broker. RabbitMQ connectivity loss causes device event processing to stop, leaving rollouts frozen in RUNNING state even as devices complete (or fail) updates.

#!/bin/bash
# /opt/monitoring/check-hawkbit-rabbitmq.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
RABBITMQ_HOST="your-rabbitmq-host"
RABBITMQ_USER="guest"
RABBITMQ_PASS="guest"

# Check RabbitMQ management API health
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -u "${RABBITMQ_USER}:${RABBITMQ_PASS}" \
  "http://${RABBITMQ_HOST}:15672/api/healthchecks/node" \
  --max-time 10)

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

Alternatively, check the queue depth to detect a growing backlog of unprocessed device events:

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

QUEUE_DEPTH=$(curl -s -u guest:guest \
  "http://your-rabbitmq-host:15672/api/queues/%2F/device_events" \
  --max-time 10 | grep -o '"messages":[0-9]*' | head -1 | cut -d: -f2)

if [ -n "$QUEUE_DEPTH" ] && [ "$QUEUE_DEPTH" -lt "$MAX_QUEUE_DEPTH" ]; then
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null
fi

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

Step 5: Monitor Rollout Progress

Hawkbit rollouts manage phased firmware deployments across device groups. A rollout entering ERROR state means update failures have crossed the configured threshold, triggering an automatic pause of the deployment.

#!/bin/bash
# /opt/monitoring/check-hawkbit-rollouts.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
HAWKBIT_USER="admin"
HAWKBIT_PASS="admin"
HAWKBIT_HOST="your-hawkbit-host"

# Fetch all running rollouts and check for ERROR state
RESPONSE=$(curl -s \
  -u "${HAWKBIT_USER}:${HAWKBIT_PASS}" \
  "http://${HAWKBIT_HOST}:8080/rest/v1/rollouts?status=running&limit=50" \
  --max-time 15)

ERROR_COUNT=$(echo "$RESPONSE" | grep -o '"status":"ERROR"' | wc -l)

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

In Vigilmon:

  1. Click Add Monitor → Cron Heartbeat.
  2. Name: Hawkbit Rollout Error State.
  3. Expected interval: 5 minutes.
  4. Grace period: 10 minutes.
  5. Schedule: */5 * * * * /opt/monitoring/check-hawkbit-rollouts.sh.

Alert recommendation: A rollout in ERROR state means Hawkbit has already paused the deployment due to excessive failures. Alert immediately so engineers can investigate before the failure window expires.

Step 6: Monitor Target Update Failure Rate

Individual device update failures accumulate against the rollout's configured failure threshold. Tracking failure counts per rollout lets you catch deteriorating device cohorts before the threshold triggers an automatic rollout pause.

#!/bin/bash
# /opt/monitoring/check-hawkbit-failures.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
HAWKBIT_USER="admin"
HAWKBIT_PASS="admin"
HAWKBIT_HOST="your-hawkbit-host"
MAX_FAILURE_PCT=10  # alert if >10% of actions are in error

# Count all actions in ERROR state across all targets
RESPONSE=$(curl -s \
  -u "${HAWKBIT_USER}:${HAWKBIT_PASS}" \
  "http://${HAWKBIT_HOST}:8080/rest/v1/targets/actions?status=error&limit=1" \
  --max-time 15)

TOTAL_ERRORS=$(echo "$RESPONSE" | grep -o '"total":[0-9]*' | head -1 | cut -d: -f2)
TOTAL_ERRORS="${TOTAL_ERRORS:-0}"

if [ "$TOTAL_ERRORS" -lt 100 ]; then
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null
fi

Adjust MAX_FAILURE_PCT and the absolute threshold based on your fleet size and acceptable failure rate.

Step 7: Monitor Download Throughput

Devices download firmware packages directly from Hawkbit (or via a configured artifact repository). High concurrent download load can saturate the download server, causing timeouts and update retries that inflate the reported failure rate.

Monitor the Hawkbit JVM's HTTP thread pool saturation via the Actuator metrics endpoint:

#!/bin/bash
# /opt/monitoring/check-hawkbit-downloads.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
HAWKBIT_HOST="your-hawkbit-host"
MAX_ACTIVE_THREADS=150  # alert when thread pool is near saturation

ACTIVE_THREADS=$(curl -s \
  "http://${HAWKBIT_HOST}:8080/actuator/metrics/tomcat.threads.busy" \
  --max-time 10 | grep -o '"value":[0-9.]*' | head -1 | cut -d: -f2 | cut -d. -f1)

if [ -n "$ACTIVE_THREADS" ] && [ "$ACTIVE_THREADS" -lt "$MAX_ACTIVE_THREADS" ]; then
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null
fi

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

Step 8: Monitor Database Connectivity

Hawkbit stores all device registrations, distribution sets, targets, and rollout state in MariaDB or MySQL. Database connectivity loss makes all Hawkbit operations fail immediately — the Management UI shows errors and the DDI API returns 500 responses to polling devices.

#!/bin/bash
# /opt/monitoring/check-hawkbit-db.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
DB_HOST="your-mariadb-host"
DB_PORT="3306"
DB_USER="hawkbit"
DB_PASS="hawkbit_password"
DB_NAME="hawkbit"

# Simple connectivity check via mysqladmin ping
if mysqladmin ping -h "${DB_HOST}" -P "${DB_PORT}" \
    -u "${DB_USER}" -p"${DB_PASS}" --silent 2>/dev/null; then
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null
fi

Set the expected interval to 1 minute with a 3-minute grace period. Database connectivity loss is a critical failure — alert immediately.

Step 9: Monitor Target Registration and Auto-Assign Health

New devices register in Hawkbit when they first contact the DDI API. Auto-assign rules then automatically assign matching distribution sets to newly registered targets. Failures in either path block new device onboarding and leave devices without update assignments.

#!/bin/bash
# /opt/monitoring/check-hawkbit-registration.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
HAWKBIT_USER="admin"
HAWKBIT_PASS="admin"
HAWKBIT_HOST="your-hawkbit-host"

# Check auto-assign rules are active and returning valid responses
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -u "${HAWKBIT_USER}:${HAWKBIT_PASS}" \
  "http://${HAWKBIT_HOST}:8080/rest/v1/targets/autoassign?limit=1" \
  --max-time 10)

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

Schedule every 5 minutes with a 10-minute grace period.

Step 10: Configure Alerting

Apply alert channels to all Hawkbit monitors:

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

Recommended thresholds:

| Monitor | Alert After | Severity | |---|---|---| | Hawkbit application health | 2 missed checks | Critical | | DDI API availability | 1 missed check | Critical | | Management API health | 2 missed checks | High | | RabbitMQ connectivity | 1 missed check | Critical | | Rollout ERROR state | 1 missed check | Critical | | Target failure rate | 1 missed check | High | | Download thread saturation | 1 missed check | High | | Database connectivity | 1 missed check | Critical | | Target registration / auto-assign | 2 missed checks | High |

Conclusion

Eclipse Hawkbit is the control plane for OTA updates across your entire IoT fleet — when it degrades, devices stop receiving critical firmware updates silently. With Vigilmon heartbeats and HTTP monitors covering the Spring Boot application, DDI API, RabbitMQ pipeline, database, and rollout health, you get immediate alerts across every failure path before devices fall behind on updates. The heartbeat-driven approach works even when Hawkbit is on an internal network with no inbound access.

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