Monitoring Structurizr with Vigilmon

Structurizr is an open-source architecture diagramming platform built around the C4 model. Teams self-host it to maintain living architecture documentation, system context diagrams, and component diagrams alongside their codebases. When the Structurizr server goes down, engineers lose access to architecture documentation at exactly the moments they need it most — during onboarding, incident response, or design reviews. Vigilmon keeps watch on your Structurizr instance so you catch failures before your engineers do.

What You'll Set Up

• HTTP uptime monitor for the Structurizr web application
• Health check for the Structurizr API endpoint
• SSL certificate expiry alerts for your Structurizr domain
• Heartbeat monitoring for diagram export and sync scripts

Prerequisites

• Self-hosted Structurizr instance running (Docker with structurizr/onpremises)
• Structurizr accessible over HTTP or HTTPS on a domain or IP
• A free Vigilmon account

Step 1: Monitor the Structurizr Web Application

The Structurizr web application is the interface your team uses to view and manage C4 model diagrams. If this endpoint is unreachable, all architecture documentation is inaccessible.

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

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

Step 2: Check the Structurizr Health Endpoint

Structurizr On-Premises exposes a /health endpoint that confirms the application is running and its internal services are reachable. Monitor it with a dedicated check:

1. Add Monitor → HTTP / HTTPS.
2. URL: https://structurizr.yourdomain.com/health.
3. Set Expected HTTP status to 200.
4. Under Advanced, set Expected body contains to {"status":"ok"} or ok to verify the response payload, not just the HTTP code.
5. Set Check interval to 1 minute.
6. Click Save.

The health endpoint is separate from the main application endpoint — it's a fast, lightweight check that bypasses authentication and rendering, so it gives you a clean signal about the application process itself.

Step 3: Monitor the Structurizr API

If your team uses the Structurizr API to push workspace updates programmatically (e.g., from a Structurizr DSL pipeline or a CI/CD job), monitor the API endpoint directly:

1. Add Monitor → HTTP / HTTPS.
2. URL: https://structurizr.yourdomain.com/api/workspace/1 — adjust the workspace ID to match your deployment.
3. Set Expected HTTP status to 200 (or 401 if the endpoint requires authentication, which still confirms the API is responding).
4. Set Check interval to 2 minutes.
5. Click Save.

A 401 Unauthorized response on an authenticated endpoint is a healthy signal — it means the API is running and rejecting unauthenticated requests as expected. Configure the expected status code accordingly.

Step 4: 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: structurizr.yourdomain.com, Port: 443 (or 8080 if your Structurizr instance 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 5: Add SSL Certificate Monitoring

A lapsed TLS certificate blocks all Structurizr access with an untrusted certificate browser error. Teams using Structurizr during incident response will be blocked at exactly the wrong time.

1. Open your Structurizr 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 team sees a certificate error page.

Step 6: Heartbeat Monitoring for Diagram Sync Pipelines

If your team uses a CI/CD pipeline to push Structurizr DSL updates to the server (e.g., via the Structurizr CLI or API), use Vigilmon's cron heartbeat to confirm these sync jobs are completing.

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

#!/bin/bash
set -e

# Push updated workspace to Structurizr
structurizr-cli push \
  -url https://structurizr.yourdomain.com \
  -id 1 \
  -key $STRUCTURIZR_API_KEY \
  -secret $STRUCTURIZR_API_SECRET \
  -workspace workspace.dsl

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

If the sync script fails before pinging, Vigilmon alerts after the expected interval passes — giving you early warning that your architecture documentation is drifting out of sync.

Step 7: 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 Structurizr 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 Structurizr 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 structurizr/onpremises && docker compose up -d

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web application | https://structurizr.yourdomain.com | Frontend down, proxy failure | | Health endpoint | /health | Application process failure | | API endpoint | /api/workspace/1 | API layer failure | | TCP port | :443 or :8080 | Network-level connectivity failure | | SSL certificate | Structurizr domain | Certificate renewal failure | | Cron heartbeat | Heartbeat URL | Diagram sync pipeline failure |

Structurizr powers your living architecture documentation — but self-hosted means you own the reliability. With Vigilmon watching the web application, health endpoint, API, TCP port, and SSL certificate, you'll know about failures in real time instead of discovering them during an incident review when the architecture diagrams are unavailable.