Monitoring Terrastruct (D2) with Vigilmon

Terrastruct's D2 is a modern diagram scripting language that compiles text into software architecture diagrams. Teams use D2 servers in CI/CD pipelines to auto-generate architecture documentation, in docs-as-code workflows to render system diagrams from source, and in internal tooling to produce consistent engineering visuals. When the D2 rendering server goes down, diagram generation fails silently and documentation falls out of date. Vigilmon monitors your Terrastruct D2 instance so you catch failures before your docs pipeline breaks.

What You'll Set Up

• HTTP uptime monitor for the D2 rendering server
• Keyword check to confirm the D2 API responds correctly
• TCP port check for network-level connectivity
• SSL certificate expiry alerts for your D2 server domain
• Heartbeat monitoring for automated diagram generation jobs

Prerequisites

• Self-hosted D2 rendering server running (Docker or binary)
• D2 server accessible over HTTP or HTTPS on a domain or IP
• A free Vigilmon account

Step 1: Monitor the D2 Rendering Server

The D2 rendering API is what your CI/CD pipelines and documentation tools call to convert .d2 source files into SVG or PNG diagrams. If this endpoint is unreachable, all automated diagram generation fails.

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

If your D2 server is behind a reverse proxy (nginx, Caddy, Traefik), the HTTP check confirms both the proxy layer and the D2 process are healthy. A 502 Bad Gateway means the D2 binary or container has stopped responding even though the proxy is still listening.

Step 2: Verify the D2 API Responds Correctly

An HTTP 200 response from the server root confirms connectivity, but doesn't confirm the D2 rendering engine is functional. Add a check against the D2 API endpoint directly:

1. Add Monitor → HTTP / HTTPS.
2. URL: https://d2.yourdomain.com/health (or your configured health route).
3. Set Expected HTTP status to 200.
4. Under Advanced, set Expected body contains to ok or the expected health response string.
5. Set Check interval to 2 minutes.
6. Click Save.

This catches scenarios where the server process is running but the D2 engine has encountered a fatal initialization error — the HTTP server answers but rendering requests would fail.

Step 3: Add a TCP Port Check

The D2 server typically serves on port 443 or a custom port. A TCP port monitor provides a low-level check independent of the HTTP layer:

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

TCP checks catch network-level failures — security group or firewall changes, Docker network misconfigurations, or port binding conflicts — before any application-layer response is possible. This is particularly useful in cloud environments where ingress rules are managed separately from application configuration.

Step 4: Add SSL Certificate Monitoring

A lapsed TLS certificate on your D2 server causes all CI/CD diagram generation to fail with TLS handshake errors. These failures often appear as cryptic pipeline errors rather than obvious certificate warnings.

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

Automated pipeline failures from certificate expiry are harder to diagnose than browser warnings. A 21-day alert window ensures you have time to renew before CI/CD starts reporting unexplained TLS errors.

Step 5: Heartbeat Monitoring for Automated Diagram Generation

D2 is frequently used in scheduled or event-driven docs pipelines that regenerate architecture diagrams on a cron schedule or triggered by code changes. Use Vigilmon's cron heartbeat to confirm these pipelines are executing successfully:

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

#!/bin/bash
# Regenerate architecture diagrams from D2 source
d2 architecture.d2 architecture.svg && \
d2 sequence.d2 sequence.svg && \
  curl -s https://vigilmon.online/heartbeat/abc123

For GitHub Actions or similar CI pipelines:

- name: Generate D2 diagrams
  run: |
    d2 docs/architecture.d2 docs/architecture.svg
    d2 docs/sequence.d2 docs/sequence.svg

- name: Ping Vigilmon heartbeat
  if: success()
  run: curl -s https://vigilmon.online/heartbeat/abc123

If your D2 pipeline stops running — due to a scheduler failure, broken CI configuration, or D2 binary update — the heartbeat stops and Vigilmon alerts you.

Step 6: Configure Alert Channels

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

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

docker pull terrastruct/d2 && docker compose up -d

Summary

| Monitor | Target | What It Catches | |---|---|---| | D2 rendering server | https://d2.yourdomain.com | Server down, proxy failure | | API health endpoint | /health | Engine initialization failure | | TCP port | :443 | Network-level connectivity failure | | SSL certificate | D2 server domain | Certificate renewal failure | | Cron heartbeat | Heartbeat URL | Automated diagram pipeline failure |

Terrastruct D2 brings architecture diagrams into your code workflows — but when the rendering server is down, your docs pipeline silently produces stale diagrams. With Vigilmon monitoring the HTTP endpoint, API health, TCP port, SSL certificate, and generation heartbeat, you'll know about failures before stale diagrams make it into your documentation.