Monitoring ZenUML with Vigilmon

ZenUML is an open-source sequence diagram tool that generates UML sequence diagrams from an intuitive, code-like syntax. Teams embed ZenUML in Confluence pages, documentation portals, and internal wikis to keep API flows, service interactions, and event-driven workflows visible alongside their code. Self-hosted ZenUML deployments give teams control over rendering and data privacy — but when the server goes offline, embedded sequence diagrams across your entire documentation portal stop rendering. Vigilmon monitors your ZenUML instance so you catch failures before engineers start reporting broken documentation.

What You'll Set Up

• HTTP uptime monitor for the ZenUML web application
• Keyword check to confirm the rendering engine loads correctly
• TCP port check for network-level connectivity
• SSL certificate expiry alerts for your ZenUML domain
• Heartbeat monitoring for Confluence or documentation integration sync jobs

Prerequisites

• Self-hosted ZenUML instance running (Docker or Node.js)
• ZenUML accessible over HTTP or HTTPS on a domain or IP
• A free Vigilmon account

Step 1: Monitor the ZenUML Web Application

The ZenUML frontend serves the diagram editor and rendering engine that your engineers and documentation consumers depend on. If this endpoint is unreachable, sequence diagrams fail to render across every page that embeds them.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your ZenUML URL: https://zenuml.yourdomain.com.
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

If ZenUML is running behind a reverse proxy (nginx, Caddy, Traefik), the HTTP check confirms both the proxy and the ZenUML process are healthy. A 502 Bad Gateway response means the ZenUML container or Node process has crashed even though the proxy is still listening.

Step 2: Verify the ZenUML Rendering Engine Loads Correctly

An HTTP 200 response confirms the server is responding, but it doesn't confirm the ZenUML rendering engine has initialized. Add a keyword check to detect misconfigured deployments that serve empty or error pages:

1. Open your ZenUML HTTP / HTTPS monitor.
2. Under Advanced, set Expected body contains to ZenUML — this string appears in every ZenUML page.
3. Click Save.

A missing environment variable, failed database connection, or JavaScript bundle error can cause ZenUML to return a blank page or error screen with a 200 HTTP status. The keyword check catches this failure mode and prevents false confidence from a passing HTTP status check.

Step 3: Add a TCP Port Check

ZenUML typically serves on port 443 or a custom port. A TCP port monitor provides a low-level connectivity check independent of the HTTP and application layers:

1. Add Monitor → TCP Port.
2. Host: zenuml.yourdomain.com, Port: 443 (or your configured port).
3. Set Check interval to 2 minutes.
4. Click Save.

TCP checks catch network-level failures — firewall changes, container networking errors, or port binding conflicts — before any HTTP response is possible. For ZenUML deployments embedded in Confluence via macro, a TCP failure means the macro can't connect to the rendering server even if the Confluence instance itself is healthy.

Step 4: Add SSL Certificate Monitoring

A lapsed TLS certificate on your ZenUML server causes Confluence macros and documentation embeds to fail with mixed-content or TLS errors — often displaying as broken diagram placeholders with cryptic error messages that are hard to trace back to a certificate issue.

1. Open your ZenUML HTTP / HTTPS monitor.
2. Enable Monitor SSL certificate under the SSL section.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

A 21-day alert window gives you enough time to renew certificates before embedded diagrams start failing across your documentation portal. TLS errors from embedded macros are especially disruptive because they affect many pages simultaneously.

Step 5: Heartbeat Monitoring for Documentation Sync Jobs

ZenUML deployments often integrate with Confluence or other documentation platforms through scheduled sync jobs that update macro registrations, diagram caches, or plugin configurations. Use Vigilmon's cron heartbeat to confirm these jobs are completing successfully:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to match your sync schedule (e.g. 60 minutes).
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. Add the heartbeat ping to your sync script:

#!/bin/bash
# Run ZenUML Confluence macro sync
node /app/scripts/confluence-sync.js && \
  curl -s https://vigilmon.online/heartbeat/abc123

For a cron-scheduled Docker container:

services:
  zenuml-sync:
    image: zenuml/sync-worker
    command: >
      sh -c "node sync.js &&
             curl -s https://vigilmon.online/heartbeat/abc123"
    restart: unless-stopped

If the sync job stops running — due to a scheduler failure, token expiry, or API error — the heartbeat stops arriving and Vigilmon alerts your team.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook for your documentation team.
2. Set Consecutive failures before alert to 2 on the main ZenUML monitor — Docker restarts and brief container recycling can cause single probe misses.
3. Use Maintenance windows to suppress alerts during ZenUML version upgrades or Confluence maintenance windows:

# Pause alerts during upgrade
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "abc123", "duration_minutes": 15}'

docker pull zenuml/app && docker compose up -d

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web application | https://zenuml.yourdomain.com | Frontend down, proxy failure | | Keyword check | Page body contains ZenUML | Blank page, rendering engine failure | | TCP port | :443 | Network-level connectivity failure | | SSL certificate | ZenUML domain | Certificate renewal failure | | Cron heartbeat | Heartbeat URL | Documentation sync job failure |

ZenUML keeps sequence diagrams embedded across your documentation portal — but when the server is down, every embedded diagram fails to render simultaneously. With Vigilmon monitoring the HTTP frontend, page content, TCP port, SSL certificate, and sync heartbeat, you'll catch failures before engineers start reporting broken documentation pages.