Monitoring D2 Diagram Server with Vigilmon

D2 is a modern declarative diagramming language — define your architecture, flow, or entity diagrams as code, and D2 renders them into crisp SVG. When run as a self-hosted rendering service, D2 integrates into documentation pipelines, GitOps workflows, and developer portals. That integration makes D2 invisible infrastructure: when it goes down, diagram assets fail silently in build pipelines and docs are published with broken images. Vigilmon lets you monitor your D2 rendering service so you catch outages before they affect downstream consumers.

What You'll Set Up

HTTP uptime monitor for the D2 render service
Render endpoint check verifying actual diagram generation
TCP port check for the D2 service listener
SSL certificate expiry alerts for your D2 domain

Prerequisites

D2 running as a self-hosted HTTP service (e.g. using d2 --host or a wrapper server)
D2 service accessible on a domain or IP
A free Vigilmon account

Step 1: Add a Health Endpoint to Your D2 Service

D2's CLI renderer (d2) does not ship with a built-in health endpoint when run as a server. If you're running D2 behind a lightweight HTTP wrapper, add a /health route that Vigilmon can probe:

// Example: minimal Go wrapper around d2 rendering
http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    w.Write([]byte(`{"status":"ok"}`))
})

For a Node.js wrapper:

app.get('/health', (req, res) => {
  res.json({ status: 'ok', uptime: process.uptime() });
});

Deploy the change and confirm the endpoint responds:

curl https://d2.yourdomain.com/health
# {"status":"ok"}

Step 2: Monitor the D2 Service Health Endpoint

Log in to vigilmon.online and click Add Monitor.
Set Type to HTTP / HTTPS.
Enter the health URL: https://d2.yourdomain.com/health.
Set Check interval to 2 minutes.
Set Expected HTTP status to 200.
Under Advanced, set Expected body contains to ok.
Click Save.

If your D2 service does not have a health endpoint yet, monitor the root URL (/) and set the expected status to whatever your wrapper returns on GET /.

Step 3: Verify Diagram Rendering End-to-End

A health endpoint confirms the server process is running, but does not verify that D2 can actually compile and render diagrams. Add a render test that sends a real D2 source and checks the SVG output:

Add Monitor → HTTP / HTTPS.
URL: https://d2.yourdomain.com/render (adjust the path to match your wrapper's render endpoint).
Set Method to POST.
Set Request body to:

x -> y: hello

Set Content-Type header to text/plain (or application/json if your wrapper expects JSON like {"source": "x -> y"}).
Set Expected HTTP status to 200.
Under Advanced, set Expected body contains to <svg to confirm SVG output was returned.
Set Check interval to 5 minutes.
Click Save.

This end-to-end render check catches cases where the D2 binary crashes, the d2 executable is missing from PATH, or a layout engine (ELK, DAGRE) fails to initialize.

Step 4: TCP Port Check for the D2 Listener

Add a TCP-level check to confirm the D2 service port is open independently of HTTP parsing:

Add Monitor → TCP Port.
Host: d2.yourdomain.com, Port: 443 (or your D2 service's actual port, e.g. 3000).
Set Check interval to 2 minutes.
Click Save.

A TCP failure when the HTTP check is passing indicates a network routing or firewall change. A TCP failure with an HTTP failure indicates the service process itself has crashed.

Step 5: SSL Certificate Expiry Monitoring

D2 render services embedded in documentation build pipelines often fail silently on certificate errors — the build tool may not surface TLS errors clearly, just a missing diagram.

Open the D2 HTTP / HTTPS monitor from Step 2.
Enable Monitor SSL certificate under the SSL section.
Set Alert when certificate expires in less than 21 days.
Click Save.

Step 6: Heartbeat for CI/CD Pipeline Integration

If your D2 service is called during CI builds (to render diagrams as build artifacts), add a heartbeat to confirm the CI integration is running successfully:

In Vigilmon, click Add Monitor → Cron Heartbeat.
Set the expected ping interval to match your build cadence (e.g. 60 minutes for an hourly CI pipeline).
Copy the heartbeat URL.
Add the ping to your CI script after a successful D2 render step:

# GitHub Actions example
- name: Render D2 diagrams
  run: |
    d2 docs/architecture.d2 docs/architecture.svg
    curl -s https://vigilmon.online/heartbeat/abc123

If the render step fails and exits non-zero, the curl never runs and Vigilmon alerts when the next expected ping doesn't arrive.

Step 7: Configure Alert Channels

Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
Set Consecutive failures before alert to 2 on the health endpoint monitor.
Set Consecutive failures before alert to 3 on the render endpoint monitor — D2 rendering can take longer for complex diagrams, and a single probe timeout may not indicate a failure.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Health endpoint | /health | Service process crash | | Render check | POST /render | D2 binary failure, layout engine crash | | TCP port | :443 or service port | Listener down, firewall change | | SSL certificate | D2 domain | Certificate renewal failure | | Cron heartbeat | Heartbeat URL | CI pipeline integration broken |

D2 diagrams defined as code belong in your version control and your build pipeline — but that pipeline integration means a D2 service outage can break builds silently. With Vigilmon watching both the health endpoint and an actual render path, you'll catch D2 failures immediately instead of discovering them when a downstream doc build fails.