Monitoring Kroki with Vigilmon

Kroki is a self-hosted service that converts diagram definitions (PlantUML, Graphviz, Mermaid, D2, and dozens more) into SVG and PNG images through a single unified API. It's often invisible infrastructure — embedded in wikis, documentation pipelines, and CI renderers — which means when it goes down, you see broken images instead of an obvious error. Vigilmon keeps your Kroki instance under watch so you catch outages before they quietly break your entire documentation toolchain.

What You'll Set Up

• HTTP uptime monitor for the Kroki service
• API render endpoint check to verify diagram generation works end-to-end
• TCP port check for the Kroki listener
• SSL certificate expiry alerts for your Kroki domain

Prerequisites

• Kroki running self-hosted (Docker or native; single-container or companion-service setup)
• Kroki accessible on a domain or IP (default port: 8000)
• A free Vigilmon account

Step 1: Monitor the Kroki HTTP Endpoint

Kroki's main interface is an HTTP API. The root endpoint returns version information and confirms the service is running.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your Kroki URL: https://kroki.yourdomain.com (or http://YOUR_HOST_IP:8000 if running without TLS).
4. Set Check interval to 2 minutes.
5. Set Expected HTTP status to 200.
6. Click Save.

The Kroki root endpoint returns a JSON response containing the version string. You can use this to confirm not just that the port is open but that Kroki itself is responding:

• Under Advanced, set Expected body contains to version to verify the JSON payload.

Step 2: Verify Diagram Rendering End-to-End

The HTTP endpoint being up does not mean Kroki can actually render diagrams. Companion containers (PlantUML server, Blockdiag, etc.) are separate processes that Kroki delegates to. If a companion crashes, Kroki returns HTTP 200 on the root but returns errors for specific diagram types.

Add a monitor that tests an actual render:

1. Add Monitor → HTTP / HTTPS.

2. URL: https://kroki.yourdomain.com/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000

   This is a Kroki GET URL encoding @startuml\nBob -> Alice: hello\n@enduml in base64 — a minimal PlantUML sequence diagram that Kroki can render without any external network access.

3. Set Expected HTTP status to 200.

4. Under Advanced, set Expected body contains to <svg to verify the SVG payload was returned, not an error body.

5. Set Check interval to 5 minutes.

6. Click Save.

Repeat for other diagram types your team depends on (Graphviz, Mermaid, etc.) by encoding a minimal definition and using the appropriate /graphviz/svg/ or /mermaid/svg/ path.

Step 3: TCP Port Check for the Kroki Listener

If Kroki is not behind a reverse proxy, the service listens directly on port 8000. A TCP check confirms the process is alive before any HTTP parsing:

1. Add Monitor → TCP Port.
2. Host: your Kroki server IP or hostname, Port: 8000 (or 443 if behind a proxy with HTTPS).
3. Set Check interval to 2 minutes.
4. Click Save.

If Kroki is behind a reverse proxy, monitor port 443 at the proxy level and add a separate HTTP check at http://localhost:8000 from a cron heartbeat on the Kroki host itself to distinguish proxy failures from Kroki failures.

Step 4: Monitor Companion Services

Kroki's multi-container Docker Compose setup includes companion services (kroki-mermaid, kroki-bpmn, kroki-excalidraw). Each is a separate container that Kroki calls over an internal network. If a companion crashes, Kroki reports errors only for that diagram type — the main service appears healthy.

Add a render check for each companion you rely on:

Mermaid companion check:

1. Add Monitor → HTTP / HTTPS.

2. URL: https://kroki.yourdomain.com/mermaid/svg/ with the base64 of graph LR\n A-->B appended.

   The full URL: https://kroki.yourdomain.com/mermaid/svg/Z3JhcGggTFIKICBBLS0-Qg

3. Expected body contains: <svg.

4. Check interval: 5 minutes.

Repeat for excalidraw, diagramsnet, and any other companion types critical to your documentation pipeline.

Step 5: SSL Certificate Alerts

Kroki is often embedded in tooling that doesn't surface certificate errors clearly — a broken diagram just fails silently in a wiki or PDF render pipeline.

1. Open the main Kroki 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.

Step 6: Configure Alert Channels

Because Kroki is usually background infrastructure, alerts should go somewhere your team will actually see them even outside business hours:

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. Set Consecutive failures before alert to 2 — Kroki containers can take a few seconds to restart.
3. For render-endpoint monitors, set Consecutive failures before alert to 3 to avoid false positives from intermittent companion delays.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Root endpoint | https://kroki.yourdomain.com | Service down, container crash | | Render check (PlantUML) | /plantuml/svg/... | PlantUML companion failure | | Render check (Mermaid) | /mermaid/svg/... | Mermaid companion failure | | TCP port | :8000 or :443 | Listener down | | SSL certificate | Kroki domain | Certificate renewal failure |

Kroki is invisible infrastructure — it silently powers every diagram in your docs, wikis, and CI pipelines. With Vigilmon checking both the root endpoint and actual render paths, you'll know when Kroki is down or degraded instead of discovering it hours later when someone notices broken images in a published document.