tutorial

Monitoring Eclipse Kura with Vigilmon

Eclipse Kura is an OSGi-based IoT gateway framework for industrial edge devices. Here's how to monitor Kura process health, MQTT cloud connectivity, field device drivers, wire graphs, OTA updates, and gateway resources with Vigilmon.

Eclipse Kura is a Java/OSGi IoT gateway framework that runs on embedded Linux edge devices — Raspberry Pis, industrial PCs, Eurotech Reliagate units — and manages everything from industrial fieldbus connections to MQTT cloud publishing. When Kura is deployed in a factory, utility meter, or smart building, it's the sole data collection layer between physical sensors and the cloud. A silent Kura crash, MQTT disconnection, or field device driver failure means data stops flowing with no visible alert unless you're actively monitoring. Vigilmon gives you remote visibility into every critical layer of a Kura gateway — even when the gateway itself is on a private industrial network behind a firewall.

What You'll Set Up

  • Kura web console availability monitor (port 443/8443)
  • MQTT cloud connectivity heartbeat
  • Field device driver health heartbeat (Modbus, OPC-UA, S7)
  • Wire graph execution health heartbeat
  • Data store / offline buffer fill level monitor
  • Remote management connectivity heartbeat
  • Gateway CPU and heap usage monitor
  • Kura OSGi bundle health monitor
  • OTA update status heartbeat

Prerequisites

  • Eclipse Kura 5.x or 6.x running on an embedded Linux gateway
  • Kura web console reachable over HTTPS (port 443 or 8443)
  • Gateway with outbound HTTPS access to vigilmon.online (for heartbeats)
  • SSH or console access for initial script deployment
  • A free Vigilmon account

Step 1: Monitor the Kura Web Console

The Kura web console (Jetty embedded in the OSGi runtime) gives you a first-class signal on whether the Java process is alive and the OSGi container is running. If the console port is unreachable, Kura has crashed or the JVM has been OOM-killed.

If your gateway has a public IP or is reachable via a VPN/tunnel:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. URL: https://gateway.yourdomain.com (or the WireGuard/VPN-accessible IP of the gateway, e.g., https://10.100.0.5).
  4. Check interval: 1 minute.
  5. Expected HTTP status: 200 (Kura redirects to the login page, which returns 200).
  6. Enable Monitor SSL certificate → set expiry alert to 21 days.
  7. Click Save.

If your gateway is on a private LAN with no inbound access, skip this monitor and use the MQTT heartbeat in Step 2 as your primary liveness signal instead.

Step 2: Monitor MQTT Cloud Connectivity via Heartbeat

Kura maintains a persistent MQTT connection to your cloud broker (AWS IoT, Azure IoT Hub, Eclipse Mosquitto, EMQX). When this connection drops — due to network outage, broker restart, or TLS certificate expiry — field data stops reaching the cloud silently.

Deploy a cron heartbeat script on the Kura gateway that sends a ping to Vigilmon only while the MQTT connection is active. Kura exposes its cloud connection status via the Kura REST API (available on localhost):

#!/bin/bash
# /opt/monitoring/check-kura-mqtt.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"

# Query Kura REST API for cloud connection status
STATUS=$(curl -s -u admin:YOUR_KURA_PASSWORD \
  http://localhost:80/services/cloudservice \
  2>/dev/null | grep -o '"connected":true')

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

In Vigilmon:

  1. Click Add Monitor → Cron Heartbeat.
  2. Name: Kura MQTT Cloud Connection.
  3. Expected interval: 2 minutes.
  4. Grace period: 5 minutes (allows for brief MQTT reconnection without false alerts).
  5. Copy the heartbeat URL into the script.
  6. On the gateway: crontab -e → add */2 * * * * /opt/monitoring/check-kura-mqtt.sh.
  7. Click Save.

Alert recommendation: A 5-minute MQTT disconnection means you're already missing data points — alert promptly.

Step 3: Monitor Field Device Driver Health

Kura drivers connect to field devices (Modbus RTU/TCP, OPC-UA servers, Siemens S7 PLCs). Driver disconnections are silent at the cloud level — Kura continues publishing empty or stale data unless you explicitly check driver status.

Deploy a driver health heartbeat that polls each driver's connection status:

#!/bin/bash
# /opt/monitoring/check-kura-drivers.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"

# Query the Kura driver status via its REST API
# Adapt the driver name to match your configuration
DRIVER_STATUS=$(curl -s -u admin:YOUR_KURA_PASSWORD \
  "http://localhost:80/services/assetservice/YOUR_ASSET_NAME/status" \
  2>/dev/null | grep -o '"connected":true')

if [ "$DRIVER_STATUS" = '"connected":true' ]; then
  curl -s -X POST "$HEARTBEAT_URL" > /dev/null
fi

Alternatively, check the timestamp of the last successful device read by querying the Kura data store:

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
MAX_STALE_SECONDS=120  # alert if no device read in 2 minutes

LAST_READ=$(cat /var/kura/driver_last_read_timestamp 2>/dev/null || echo 0)
NOW=$(date +%s)
AGE=$((NOW - LAST_READ))

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

Update the timestamp file from your Kura driver configuration or custom OSGi bundle.

Step 4: Monitor Wire Graph Execution Health

Kura Wire Graphs define the data flow pipeline from field devices to cloud — wiring together drivers, filters, data transformation components, and cloud publishers. A wire graph component entering a FAILED state stops the entire data pipeline for that graph.

#!/bin/bash
# /opt/monitoring/check-kura-wiregraph.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"

# Check wire graph component status via Kura REST API
# Returns the health of all wire components
FAILED=$(curl -s -u admin:YOUR_KURA_PASSWORD \
  "http://localhost:80/services/wiregraph" \
  2>/dev/null | grep -c '"status":"FAILED"')

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

Add a cron heartbeat in Vigilmon with a 2-minute interval and a 3-minute grace period. Any FAILED wire graph component stops the heartbeat and triggers an alert.

Step 5: Monitor the Data Store / Offline Buffer

When the MQTT connection drops, Kura buffers outgoing messages in a local data store (H2 database by default). If the buffer fills to capacity, Kura starts dropping the oldest messages. Monitor the buffer fill level to catch sustained connectivity outages before data loss occurs.

#!/bin/bash
# /opt/monitoring/check-kura-datastore.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
KURA_DATA_DIR="/var/kura/data"
THRESHOLD_MB=500  # alert when buffer exceeds 500 MB

USAGE_MB=$(du -sm "$KURA_DATA_DIR" 2>/dev/null | awk '{print $1}')
if [ -n "$USAGE_MB" ] && [ "$USAGE_MB" -lt "$THRESHOLD_MB" ]; 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. A filling buffer is a lagging indicator — you have time to act before messages are dropped.

Step 6: Monitor Remote Management Connectivity

Kura connects to a management server (Eclipse Kapua, Eurotech Everyware Cloud, or a custom LWM2M server) for remote configuration, software bundle deployment, and diagnostics. If this channel breaks, you lose the ability to push configuration changes or debug issues remotely.

#!/bin/bash
# /opt/monitoring/check-kura-mgmt.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"

# Check Kura management channel connectivity
# Kura logs a periodic heartbeat to the management server — check last log entry
LAST_HB=$(grep "Management heartbeat sent" /var/log/kura/kura.log 2>/dev/null \
  | tail -1 | awk '{print $1, $2}')

if [ -n "$LAST_HB" ]; then
  LAST_HB_TS=$(date -d "$LAST_HB" +%s 2>/dev/null || echo 0)
  NOW=$(date +%s)
  AGE=$((NOW - LAST_HB_TS))
  if [ "$AGE" -lt 300 ]; then  # heartbeat within 5 minutes
    curl -s -X POST "$HEARTBEAT_URL" > /dev/null
  fi
fi

Step 7: Monitor Gateway Resource Usage

Kura runs on constrained edge hardware. High CPU usage causes data collection gaps; heap exhaustion causes JVM OOM kills. Monitor both at a 5-minute interval:

#!/bin/bash
# /opt/monitoring/check-kura-resources.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"
MAX_CPU=85
MAX_HEAP_PCT=80

# CPU usage over the last minute
CPU=$(top -bn1 | grep "Cpu(s)" | awk '{print $2}' | cut -d. -f1)

# JVM heap usage via jstat (requires JDK on gateway)
HEAP_USED=$(jstat -gc $(pgrep -f kura) 2>/dev/null | awk 'NR==2{print $3+$4}')
HEAP_MAX=$(jstat -gc $(pgrep -f kura) 2>/dev/null | awk 'NR==2{print $5+$7}')
HEAP_PCT=0
if [ -n "$HEAP_MAX" ] && [ "$HEAP_MAX" != "0" ]; then
  HEAP_PCT=$(( (HEAP_USED * 100) / HEAP_MAX ))
fi

if [ "$CPU" -lt "$MAX_CPU" ] && [ "$HEAP_PCT" -lt "$MAX_HEAP_PCT" ]; 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.

Step 8: Monitor OSGi Bundle Health

Kura's modular OSGi architecture depends on bundles being in ACTIVE state. Critical bundles (cloud publisher, driver manager, wire service) entering RESOLVED or FAILED state silently disable Kura capabilities without stopping the JVM.

#!/bin/bash
# /opt/monitoring/check-kura-bundles.sh
HEARTBEAT_URL="https://vigilmon.online/api/v1/heartbeat/YOUR_HEARTBEAT_ID"

# Check OSGi bundle states via Kura's Gogo shell (telnet or SSH)
# Adapt to your Kura version and shell access method
FAILED_BUNDLES=$(ssh -o StrictHostKeyChecking=no kura@localhost \
  "echo 'lb | grep -E \"FAILED|Installed\"' | telnet localhost 5002 2>/dev/null" 2>/dev/null \
  | grep -c "FAILED\|Installed")

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

Alternatively, check the Kura log for bundle activation failures:

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

# Count BundleException entries in the last 5 minutes
ERRORS=$(find /var/log/kura -name "*.log" -newer /tmp/kura-bundle-check \
  -exec grep -c "BundleException\|Bundle FAILED" {} + 2>/dev/null | awk -F: '{sum+=$2}END{print sum}')
touch /tmp/kura-bundle-check

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

Step 9: Configure Alerting

Apply alert channels to all Kura monitors with appropriate thresholds:

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

Recommended thresholds:

| Monitor | Alert After | Severity | |---|---|---| | Kura web console | 2 missed checks | Critical | | MQTT cloud connection | 1 missed check | Critical | | Field device driver | 1 missed check | High | | Wire graph execution | 1 missed check | High | | Data store fill level | 1 missed check | High | | Remote management | 2 missed checks | Medium | | CPU + heap usage | 1 missed check | High | | OSGi bundle health | 1 missed check | High |

Conclusion

An Eclipse Kura gateway is often the sole data bridge between an industrial floor and the cloud — there's no redundancy when the gateway itself fails. With Vigilmon heartbeats driven by on-device scripts, you get remote visibility into MQTT connectivity, field device driver status, wire graph health, data buffer fill, and JVM resource usage without requiring inbound access to the gateway. When any layer degrades, you know immediately and can act before data gaps accumulate.

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