Monitoring Eclipse Ditto with Vigilmon

Eclipse Ditto is an open source IoT digital twin framework from Bosch that gives every physical device — sensor, actuator, machine, vehicle — a persistent digital representation in the cloud. Applications read and write device state through the Ditto API without caring whether the physical device is currently connected. Behind the scenes, Ditto runs as a cluster of Akka-based microservices (Gateway, Things, Policies, Connectivity, Search) backed by MongoDB. Any service failure silently breaks the digital twin layer: API calls fail, device state updates stop, or device commands can't reach their targets. Vigilmon gives you visibility across every Ditto service, the Akka cluster, MongoDB, and the broker connections that link Ditto to your physical device fleet.

What You'll Set Up

• Gateway service HTTP health monitor (the API entry point)
• Things service health monitor (digital twin persistence)
• Policies service health monitor (access control)
• Connectivity service health monitor (device broker connections)
• MongoDB health monitor
• Thing event throughput heartbeat
• Live message delivery rate heartbeat
• Akka cluster health heartbeat
• Search service health monitor
• API response latency heartbeat

Prerequisites

• Eclipse Ditto deployed via Docker Compose or Kubernetes (Helm chart)
• Ditto Gateway accessible on port 8080 (HTTP) and/or 8443 (HTTPS)
• MongoDB accessible and backing all Ditto services
• A free Vigilmon account

Step 1: Monitor the Ditto Gateway Service

The Ditto Gateway is the API entry point for all external clients — it handles REST API calls, WebSocket connections, and Server-Sent Events (SSE). Every application reading or writing digital twin state goes through the gateway. If the gateway goes down, all Thing reads and writes fail for all connected applications.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. URL: http://your-ditto-host:8080/health.
4. Expected HTTP status: 200.
5. Keyword check: enter UP or healthy (Ditto's health endpoint returns a status JSON).
6. Check interval: 1 minute.
7. Set Alert after: 1 failure — the gateway is the sole external API; any downtime is a full outage.
8. Click Save.

If you have TLS enabled, use the HTTPS URL:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://your-ditto-host:8443/health.
3. Enable SSL certificate monitoring and set the alert threshold to 21 days.
4. Check interval: 1 minute.
5. Click Save.

Also add a Vigilmon monitor on the gateway's metrics endpoint to verify the service is processing requests:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-ditto-host:8080/metrics.
3. Expected HTTP status: 200.
4. Keyword check: enter gateway to verify gateway-specific metrics are present.
5. Check interval: 2 minutes.
6. Click Save.

Step 2: Monitor the Things Service

The Things service persists digital twin state — the JSON documents for every Thing in Ditto. It stores Features (device properties), attributes, and Thing metadata in MongoDB. If the Things service loses a cluster node, requests to read or write Thing state may fail or become slower as the cluster rebalances.

Ditto exposes an internal health endpoint per service. The Things service typically runs on its own internal port. Monitor it via the gateway's /devops/health endpoint (requires DevOps credentials):

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-ditto-host:8080/devops/health.
3. Method: GET.
4. Auth header: Authorization: Basic <base64(devops:password)> — add this in Vigilmon's Custom Headers.
5. Expected HTTP status: 200.
6. Keyword check: enter things to verify the Things service is included in the cluster health response.
7. Check interval: 2 minutes.
8. Click Save.

If you access service-level ports directly (Ditto services are typically internal), monitor the Things service JVM health via its Akka management port:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://things-service-host:8558/alive.
3. Expected HTTP status: 200.
4. Check interval: 1 minute.
5. Click Save.

Step 3: Monitor the Policies Service

The Policies service manages access control for all Things — every Thing read and write is authorized against a Policy document. If the Policies service goes down, the gateway returns authorization errors for all API calls, even for clients with valid credentials.

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://policies-service-host:8558/alive.
3. Expected HTTP status: 200.
4. Check interval: 1 minute.
5. Set Alert after: 1 failure — Policies failure is a complete API outage.
6. Click Save.

Monitor the Policies service via the DevOps health endpoint:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-ditto-host:8080/devops/health.
3. Keyword check: policies.
4. Check interval: 2 minutes.
5. Click Save.

Step 4: Monitor the Connectivity Service

The Connectivity service manages outbound and inbound connections to message brokers — MQTT brokers, AMQP brokers (RabbitMQ, Qpid Dispatch), Apache Kafka, and Kinesis. Physical devices connect to Ditto through these broker connections. If Connectivity loses a connection, the corresponding devices can no longer push state updates to their digital twins or receive live messages from Ditto.

Monitor the Connectivity service health:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://connectivity-service-host:8558/alive.
3. Expected HTTP status: 200.
4. Check interval: 1 minute.
5. Click Save.

Check the broker connection count via the Ditto API (requires authentication):

#!/bin/bash
# Check that all expected Ditto connections are in OPEN state
CONNECTIONS=$(curl -s -u devops:password \
  "http://your-ditto-host:8080/api/2/connections?limit=100")
FAILED=$(echo "$CONNECTIONS" | python3 -c \
  "import sys,json; conns=json.load(sys.stdin); \
   print(sum(1 for c in conns if c.get('connectionStatus','') != 'open'))")

if [ "$FAILED" -eq "0" ]; then
  curl -fsS -m 10 "https://vigilmon.online/api/push/YOUR_CONN_KEY" > /dev/null
fi

Add a Vigilmon heartbeat monitor (expected interval: 5 minutes) for this script, scheduled in crontab:

*/5 * * * * /opt/monitoring/ditto-connections-check.sh

Step 5: Monitor MongoDB

Ditto persists all Things and Policies documents in MongoDB. MongoDB connectivity loss causes all Thing reads and writes to fail immediately. Replica set health also matters — if the primary becomes unavailable, writes fail until a new primary is elected.

Monitor the MongoDB port:

1. Click Add Monitor → TCP Port.
2. Host: mongodb-host.yourdomain.com, Port: 27017.
3. Check interval: 30 seconds.
4. Set Alert after: 1 failure.
5. Click Save.

If MongoDB has a monitoring HTTP endpoint (via MongoDB Ops Manager or the mongostat HTTP interface), add an HTTP monitor. For a replica set, use a heartbeat to check primary status:

#!/bin/bash
# Check MongoDB replica set primary is healthy
RS_STATUS=$(mongosh --host mongodb-host:27017 --eval \
  "JSON.stringify(rs.status())" --quiet 2>/dev/null)

PRIMARY=$(echo "$RS_STATUS" | python3 -c \
  "import sys,json; status=json.loads(sys.stdin.read()); \
   members=status.get('members',[]); \
   print(sum(1 for m in members if m.get('stateStr')=='PRIMARY'))")

if [ "$PRIMARY" -gt "0" ]; then
  curl -fsS -m 10 "https://vigilmon.online/api/push/YOUR_MONGO_KEY" > /dev/null
fi

Set the heartbeat interval to 2 minutes.

Step 6: Monitor Thing Event Throughput

When physical devices are connected and sending state updates, Ditto publishes Thing modification events (ThingModified, FeatureModified). The event rate reflects whether devices are actually connected and whether the Connectivity service is routing updates correctly. A drop to zero indicates devices disconnected or the event pipeline broke.

Add a heartbeat monitor for your event throughput checker:

1. Click Add Monitor → Heartbeat / Cron.
2. Expected interval: 5 minutes.
3. Copy the heartbeat URL.
4. Click Save.

Use the Ditto metrics endpoint to track events published:

#!/bin/bash
# Check that Things events are flowing
METRICS=$(curl -s http://your-ditto-host:8080/metrics)
EVENT_COUNT=$(echo "$METRICS" | grep -oP 'things_modified_total\s+\K[0-9]+' | head -1)

LAST_FILE=/tmp/ditto_last_events
LAST=$(cat "$LAST_FILE" 2>/dev/null || echo "0")

if [ "${EVENT_COUNT:-0}" -gt "$LAST" ]; then
  curl -fsS -m 10 "https://vigilmon.online/api/push/YOUR_EVENTS_KEY" > /dev/null
fi

echo "${EVENT_COUNT:-$LAST}" > "$LAST_FILE"

Step 7: Monitor Live Message Delivery

Live messages in Ditto are direct command-response exchanges with connected devices — for example, sending a "reboot" command to a connected machine or querying its current sensor reading directly. Live message delivery requires that the target device is currently connected through the Connectivity service.

Add a heartbeat that verifies live message delivery success rate:

#!/bin/bash
# Check Ditto live message delivery success rate via metrics
METRICS=$(curl -s http://your-ditto-host:8080/metrics)
FAILED=$(echo "$METRICS" | grep -c 'live_messages.*error' || true)

if [ "$FAILED" -eq "0" ]; then
  curl -fsS -m 10 "https://vigilmon.online/api/push/YOUR_LIVE_MSG_KEY" > /dev/null
fi

Set heartbeat interval to 5 minutes.

Step 8: Monitor Akka Cluster Health

All Ditto services (Things, Policies, Connectivity, Search) run as nodes in an Akka cluster. If a node becomes unreachable or leaves the cluster (due to a crash, network partition, or GC pause), the cluster attempts to recover — but split-brain scenarios can cause data inconsistency. Monitor Akka cluster membership via the Akka management HTTP API:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://things-service-host:8558/cluster/members.
3. Expected HTTP status: 200.
4. Keyword check: enter Up to verify all expected cluster members are in the Up state.
5. Check interval: 1 minute.
6. Click Save.

For a more precise cluster health check:

#!/bin/bash
# Check that all Ditto Akka cluster members are Up
CLUSTER=$(curl -s http://things-service-host:8558/cluster/members)
DOWN=$(echo "$CLUSTER" | python3 -c \
  "import sys,json; c=json.load(sys.stdin); \
   print(sum(1 for m in c.get('members',[]) if m.get('status')!='Up'))")

UNREACHABLE=$(echo "$CLUSTER" | python3 -c \
  "import sys,json; c=json.load(sys.stdin); \
   print(len(c.get('unreachable',[])))")

if [ "$DOWN" -eq "0" ] && [ "$UNREACHABLE" -eq "0" ]; then
  curl -fsS -m 10 "https://vigilmon.online/api/push/YOUR_AKKA_KEY" > /dev/null
fi

Set the heartbeat to 2 minutes. Akka cluster splits are rare but catastrophic — detect them immediately.

Step 9: Monitor the Search Service

Ditto provides a Thing search API that lets you query digital twins by property values (e.g., find all Things where temperature > 50). The search index is maintained by the Search service, which consumes Thing modification events. If the Search service falls behind (index lag) or crashes, search queries return stale results or fail.

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://search-service-host:8558/alive.
3. Expected HTTP status: 200.
4. Check interval: 1 minute.
5. Click Save.

Also verify the search index is being updated by checking the search API:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-ditto-host:8080/api/2/search/things?filter=exists(thingId)&limit=1.
3. Auth header: Authorization: Basic <base64(user:password)>.
4. Expected HTTP status: 200.
5. Keyword check: items.
6. Check interval: 5 minutes.
7. Click Save.

Step 10: Monitor API Response Latency

Ditto is designed to serve Thing reads in milliseconds. If Things service or MongoDB is overloaded, API latency climbs above 1 second and becomes noticeable to applications. Monitor end-to-end API latency with a heartbeat script:

#!/bin/bash
# Measure Ditto API latency for a known Thing
START=$(date +%s%3N)
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
  -u user:password \
  "http://your-ditto-host:8080/api/2/things/com.example:thing-001" \
  --max-time 5)
END=$(date +%s%3N)
LATENCY=$((END - START))

# Alert if latency > 1000ms or request failed
if [ "$HTTP_CODE" = "200" ] && [ "$LATENCY" -lt "1000" ]; then
  curl -fsS -m 10 "https://vigilmon.online/api/push/YOUR_LATENCY_KEY" > /dev/null
fi

Set the heartbeat interval to 2 minutes. Latency above 1 second or HTTP failures suppress the heartbeat and trigger a Vigilmon alert.

Step 11: Configure Alerting

Open Alert Channels in Vigilmon and configure notification routing:

Critical alerts (immediate, 24/7):

• Gateway HTTP failure (complete API outage for all applications)
• MongoDB TCP failure (all Thing reads/writes fail)
• Policies service down (all API calls return 403)
• Akka cluster health heartbeat missed (cluster instability)

Warning alerts (business hours or on-call):

• Connectivity service down (devices lose digital twin sync)
• Search service down (search queries fail)
• Thing event throughput heartbeat missed (device updates stopped)
• API latency heartbeat missed (response time SLA breach)

Recommended alert settings:

• Gateway: alert after 1 failure
• MongoDB: alert after 1 failure (no writes succeed without it)
• Other services: alert after 2 consecutive failures
• Heartbeats: alert after 1 missed ping

Summary: Your Eclipse Ditto Monitoring Stack

| Monitor | Type | What It Catches | |---|---|---| | Gateway :8080/health | HTTP | Complete API outage | | Gateway SSL :8443 | HTTP + SSL | Certificate expiry | | DevOps health endpoint | HTTP | Multi-service cluster health | | Things service :8558/alive | HTTP | Digital twin persistence failure | | Policies service :8558/alive | HTTP | Access control service failure | | Connectivity service :8558/alive | HTTP | Device broker connection loss | | Ditto connections heartbeat | Heartbeat | Individual broker connection failures | | MongoDB TCP :27017 | TCP Port | Database connectivity loss | | MongoDB replica set heartbeat | Heartbeat | Primary election failure | | Thing event throughput heartbeat | Heartbeat | Device updates stopped flowing | | Live message heartbeat | Heartbeat | Device command delivery errors | | Akka cluster heartbeat | Heartbeat | Cluster member unreachable | | Search service :8558/alive | HTTP | Search index failure | | API latency heartbeat | Heartbeat | Response time SLA breach |

Eclipse Ditto's digital twin model means a failure anywhere in the stack — a lost broker connection, a MongoDB primary election, an Akka cluster split — silently desynchronizes physical devices from their digital representations. Vigilmon makes every layer observable so you catch issues before applications notice stale or missing twin state.

Get started free at vigilmon.online.