Monitoring Evidence.dev with Vigilmon

Evidence.dev is a BI-as-code framework that lets you write data reports using SQL and Markdown, then compiles them into fast static sites. Your reports are only as good as the last successful build — if a data source connection fails or a scheduled rebuild crashes, your users see outdated numbers with no indication anything went wrong. Vigilmon monitors the Evidence dev server, the deployed static site, data source connectivity, and scheduled report build heartbeats so you catch failures before stakeholders do.

What You'll Set Up

HTTP monitor for the Evidence dev server availability
HTTP monitor for the deployed static site health
Heartbeat monitoring for scheduled report builds
SSL certificate alerts for deployed report sites

Prerequisites

Evidence.dev project initialized (npx degit evidence-dev/template my-project)
A deployed Evidence site (Netlify, Vercel, or self-hosted static hosting)
A Vigilmon free account

Step 1: Monitor the Evidence Dev Server

During development, Evidence runs a local dev server (default port 3000) that watches your .md query files and rebuilds on change. If you run the dev server in a shared environment or on a remote development machine, monitor its availability:

Log in to vigilmon.online and click Add Monitor.
Set Type to HTTP / HTTPS.
Enter the dev server URL: http://your-dev-server:3000/
Set Check interval to 2 minutes.
Set Expected HTTP status to 200.
Click Save.

Verify the dev server is running:

curl -I http://your-dev-server:3000/
# HTTP/1.1 200 OK
# Content-Type: text/html

The Evidence dev server crashes if it encounters a malformed SQL query or a data source connection error. Monitoring it catches silent crashes in shared development environments.

Step 2: Monitor the Deployed Static Site

Evidence builds compile to a static site that you deploy to a CDN or static host. Monitor the deployed site's availability independently from the dev server:

Click Add Monitor → HTTP / HTTPS.
Enter your deployed site URL: https://reports.yourdomain.com/
Set Check interval to 1 minute.
Set Expected HTTP status to 200.
Click Save.

For sites deployed to Netlify or Vercel, the static hosting platform is highly available, but you may still want to monitor a specific report page that exercises your data pipeline:

Click Add Monitor → HTTP / HTTPS.
Enter a specific report URL: https://reports.yourdomain.com/sales/monthly
Set Check interval to 5 minutes.
Set Expected HTTP status to 200.
Click Save.

If that page returns a 404 or 500, a recent deployment may have broken the build output.

Step 3: Monitor Data Source Connection Endpoints

Evidence connects to data sources (PostgreSQL, BigQuery, DuckDB, Snowflake, etc.) at build time. A data source that becomes unreachable will silently produce a failed build — or worse, produce a build with empty query results that looks valid.

PostgreSQL data source

Add a TCP port monitor for your PostgreSQL database:

Click Add Monitor → TCP Port.
Enter Host: your-postgres-host.com.
Enter Port: 5432.
Set Check interval to 1 minute.
Click Save.

Verifying source connectivity from Evidence

Add a connection health check to your Evidence build script:

#!/bin/bash
# /usr/local/bin/check-evidence-sources.sh

# Test PostgreSQL connectivity
pg_isready -h your-postgres-host.com -p 5432 -U evidence_user
if [ $? -ne 0 ]; then
    echo "PostgreSQL not reachable — Evidence build will fail"
    exit 1
fi

echo "Data sources OK"

For other source types, use the appropriate connectivity test before triggering a build.

Step 4: Heartbeat Monitoring for Scheduled Report Builds

Evidence reports are static — they only reflect the data at the time of the last build. If you rebuild on a schedule (hourly, daily, or triggered by data pipeline completion), Vigilmon heartbeats confirm each rebuild completes successfully.

In Vigilmon, click Add Monitor → Cron Heartbeat.
Set the expected ping interval to match your build schedule (e.g. 60 minutes for hourly rebuilds, 1440 minutes for daily).
Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).

Netlify build triggers with heartbeat

Use Netlify's deploy webhook and hook into the deploy success notification:

#!/bin/bash
# /usr/local/bin/trigger-evidence-rebuild.sh
# Triggered by your data pipeline on completion

NETLIFY_BUILD_HOOK="https://api.netlify.com/build_hooks/your-hook-id"
VIGILMON_HEARTBEAT="https://vigilmon.online/heartbeat/abc123"

# Trigger Netlify rebuild
BUILD_RESPONSE=$(curl -s -X POST "$NETLIFY_BUILD_HOOK")

if echo "$BUILD_RESPONSE" | grep -q '"id"'; then
    echo "Netlify build triggered: $BUILD_RESPONSE"
    # Note: ping heartbeat after deploy completes, not after trigger
    # Use a Netlify deploy notification webhook to call the heartbeat
else
    echo "Failed to trigger Netlify build" >&2
    exit 1
fi

For self-hosted Evidence builds with direct access to the build process:

#!/bin/bash
# /usr/local/bin/build-evidence.sh

cd /var/www/evidence-project

# Pull latest SQL/Markdown from git
git pull origin main

# Build Evidence site
npm run build 2>&1 | tee /var/log/evidence-build.log

if [ ${PIPESTATUS[0]} -eq 0 ]; then
    # Deploy the built files
    rsync -av --delete build/ /var/www/html/reports/

    # Signal successful build to Vigilmon
    curl -s --max-time 10 https://vigilmon.online/heartbeat/abc123
    echo "Evidence rebuild completed successfully at $(date)"
else
    echo "Evidence build FAILED at $(date)" >&2
    cat /var/log/evidence-build.log >&2
    exit 1
fi

Add to crontab for scheduled daily rebuilds:

0 7 * * * /usr/local/bin/build-evidence.sh >> /var/log/evidence-rebuild.log 2>&1

If the Evidence build exits non-zero (due to a SQL error, missing data source, or schema change), the heartbeat ping is skipped and Vigilmon alerts after the interval passes.

Step 5: SSL Certificate Alerts for Deployed Reports

Deployed Evidence sites should always run over HTTPS. Monitor the certificate for your report domain:

Open the HTTP / HTTPS monitor for https://reports.yourdomain.com/.
Enable Monitor SSL certificate.
Set Alert when certificate expires in less than 21 days.
Click Save.

For Netlify and Vercel deployments, certificates are auto-renewed by the platform. For self-hosted deployments with Let's Encrypt:

# Check current certificate expiry
openssl s_client -connect reports.yourdomain.com:443 -showcerts </dev/null 2>/dev/null | \
  openssl x509 -noout -enddate
# notAfter=Jun 15 12:00:00 2026 GMT

Set up auto-renewal with certbot if not already configured:

# Add to crontab (runs twice daily)
0 0,12 * * * certbot renew --quiet --post-hook "systemctl reload nginx"

A 21-day Vigilmon alert gives you three weeks to investigate and fix auto-renewal failures before your reports become inaccessible over HTTPS.

Step 6: Configure Alert Channels

Go to Alert Channels in Vigilmon and add email, Slack, or a webhook.
For the deployed static site monitor, set Consecutive failures before alert to 2 — CDN edge flaps can cause isolated misses.
For the dev server monitor, set Consecutive failures to 3 — dev servers can be slow under heavy query recompilation.
For heartbeat monitors, any missed ping should alert immediately — a failed build means stale reports.

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP (dev server) | http://host:3000/ | Dev server crash, SQL compilation error | | HTTP (deployed site) | https://reports.domain.com/ | Hosting outage, broken deployment | | HTTP (report page) | https://reports.domain.com/sales | Missing page from failed build | | TCP port (PostgreSQL) | postgres-host:5432 | Data source unreachable at build time | | Cron heartbeat | Heartbeat URL | Failed or skipped scheduled report rebuild | | SSL certificate | Report domain cert | Certificate expiry before renewal |

Evidence.dev makes BI reporting as maintainable as application code — but "BI as code" means your reports can fail to build just like application builds do. With Vigilmon watching your deployed site, data source connectivity, SSL certificates, and rebuild heartbeats, you'll catch broken reports before your stakeholders discover them.