Monitoring PlantUML Server with Vigilmon

PlantUML Server is an open-source rendering service that converts PlantUML text into diagrams. Teams self-host it to power documentation pipelines, Confluence integrations, and CI-generated architecture diagrams. When the server goes down, documentation builds fail and engineers see broken image placeholders instead of diagrams — often without a clear error message. Vigilmon keeps watch on your PlantUML server so you know before your pipelines do.

What You'll Set Up

• HTTP uptime monitor for the PlantUML Server web UI
• Health check for the PlantUML rendering API endpoint
• SSL certificate expiry alerts for your PlantUML domain
• Heartbeat monitoring for diagram generation scripts

Prerequisites

• Self-hosted PlantUML Server running (Docker, Jetty WAR, or Spring Boot)
• PlantUML Server accessible over HTTP or HTTPS on a domain or IP
• A free Vigilmon account

Step 1: Monitor the PlantUML Server Web Interface

The PlantUML Server homepage provides the web form for rendering diagrams interactively. If this endpoint is unreachable, both the web UI and the API are down.

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

If PlantUML Server runs behind a reverse proxy (nginx, Caddy, Traefik), the HTTP check confirms both the proxy and the Jetty/Spring process are healthy. A 502 Bad Gateway means the JVM process has crashed even though the proxy is still listening.

Step 2: Check the PlantUML Rendering API

The PlantUML Server exposes a rendering API that CI pipelines and documentation tools call directly. Monitor the API endpoint with a known-good diagram payload to confirm the rendering pipeline is fully functional, not just accepting connections.

1. Add Monitor → HTTP / HTTPS.
2. URL: https://plantuml.yourdomain.com/png/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000 — this is a pre-encoded "Hello World" PlantUML diagram URL.
3. Set Expected HTTP status to 200.
4. Under Advanced, set Expected body contains to leave blank (the response is a PNG binary, not text).
5. Set Check interval to 2 minutes.
6. Click Save.

The encoded path (SyfFKj2rKt3CoKnELR1Io4ZDoSa70000) is the deflate-compressed, base64-encoded representation of a minimal valid PlantUML diagram. If the rendering engine fails, the server returns a 400 or 500 instead of a PNG.

Alternatively, use the /svg/ endpoint if you prefer a text-based response for body verification:

https://plantuml.yourdomain.com/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000

Set Expected body contains to <svg to confirm a valid SVG was rendered.

Step 3: Add a TCP Port Check

A TCP port monitor provides a low-level connectivity check independent of the HTTP layer:

1. Add Monitor → TCP Port.
2. Host: plantuml.yourdomain.com, Port: 443 (or 8080 if your PlantUML Server is exposed directly without a reverse proxy).
3. Set Check interval to 2 minutes.
4. Click Save.

This catches network-level failures — container networking issues, JVM port binding failures, or firewall rule changes — that block access before the HTTP layer has a chance to respond.

Step 4: Add SSL Certificate Monitoring

A lapsed TLS certificate causes all PlantUML API consumers to fail with SSL errors. Documentation pipelines and Confluence integrations may fail silently or surface confusing error messages.

1. Open your PlantUML 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.

With a 21-day lead time, you have three weeks to renew or investigate Let's Encrypt auto-renewal failures before your CI pipelines start failing.

Step 5: Heartbeat Monitoring for Documentation Generation Scripts

If your team runs scheduled scripts that generate PlantUML diagrams (nightly documentation builds, architecture diagram exports), use Vigilmon's cron heartbeat to confirm these jobs are completing.

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to match your generation schedule (e.g. 1440 minutes for a nightly job).
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. Add the ping at the end of your generation script:

#!/bin/bash
set -e

# Generate diagrams from PlantUML sources
find ./docs -name "*.puml" | while read f; do
  curl -sf "https://plantuml.yourdomain.com/png/$(plantuml-encode "$f")" \
    -o "${f%.puml}.png"
done

# Ping Vigilmon to confirm the job completed
curl -s https://vigilmon.online/heartbeat/abc123

If the script exits with an error before pinging, Vigilmon alerts after the expected interval passes.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook endpoint.
2. Set Consecutive failures before alert to 2 on the main PlantUML monitor — Docker restarts and JVM warm-up cycles can cause a single probe miss.
3. Use Maintenance windows in Vigilmon to suppress alerts when deploying a new PlantUML version:

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

docker pull plantuml/plantuml-server && docker compose up -d

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web interface | https://plantuml.yourdomain.com | Server down, proxy failure | | Rendering API | /svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000 | Rendering engine failure | | TCP port | :443 or :8080 | Network-level connectivity failure | | SSL certificate | PlantUML domain | Certificate renewal failure | | Cron heartbeat | Heartbeat URL | Documentation generation job crash |

PlantUML Server powers your documentation pipelines and architecture diagrams — but self-hosted means you own the reliability. With Vigilmon watching the web interface, rendering API, TCP port, and SSL certificate, you'll know about failures in real time instead of discovering them when a CI build produces broken diagram placeholders.