Monitoring Turborepo Pipelines with Vigilmon

Turborepo is a high-performance build system for JavaScript and TypeScript monorepos. Its remote caching and intelligent task scheduling cut build times dramatically — but when the remote cache is unreachable, hit rates fall through the floor, or a slow task holds up every downstream job, you won't know until your CI queue is already backed up. Vigilmon gives you the runtime visibility to catch those problems before they become outages: HTTP health checks on your cache backend, cron heartbeats on pipeline runs, and webhook alerts when build durations spike.

What You'll Set Up

• HTTP uptime monitor for the Turborepo remote cache endpoint
• Cron heartbeat to confirm nightly full-build pipelines complete on schedule
• Webhook integration to alert on cache hit rate degradation
• SSL certificate monitoring for self-hosted cache servers
• API-driven maintenance windows around cache deploys

Prerequisites

• Turborepo 1.x or 2.x monorepo with turbo.json pipeline configured
• Remote cache backend (Vercel Remote Cache, self-hosted turborepo-remote-cache, or Nx Cloud)
• CI provider running turbo run build test lint on pull requests
• A free Vigilmon account

Step 1: Monitor Your Remote Cache Endpoint

Turborepo's remote cache is the single biggest performance multiplier in your monorepo — and the single biggest point of failure. When it's unreachable, every task runs cold regardless of whether the code changed.

Most remote cache backends expose a health endpoint. Add a Vigilmon HTTP monitor for it:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your cache server URL. Common examples:
   • Self-hosted turborepo-remote-cache: https://turbocache.yourdomain.com/v8/artifacts/status
   • Vercel Remote Cache: https://api.vercel.com/v8/artifacts/status (authenticated — use the webhook approach in Step 3 instead)
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

For the self-hosted cache server, the /v8/artifacts/status path returns {"status":"enabled"} when the server is healthy. Any non-200 response triggers an alert before your next CI run hits a cold cache.

If your cache backend doesn't expose a public health endpoint, monitor the host's TCP port instead:

1. Click Add Monitor → TCP Port.
2. Enter the hostname and port (typically 443 for HTTPS cache servers).
3. Set Check interval to 1 minute.

Step 2: Add a Health Endpoint to a Self-Hosted Cache Server

If you're running turborepo-remote-cache (the open-source server), it already exposes /v8/artifacts/status. Verify it's working:

curl -s https://turbocache.yourdomain.com/v8/artifacts/status
# {"status":"enabled"}

If you're behind an nginx reverse proxy, make sure the health path isn't blocked:

location /v8/artifacts/status {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    # Allow unauthenticated health checks from Vigilmon
    auth_basic off;
}

For a custom cache backend, add a /health route that checks storage connectivity:

// Express example
app.get('/health', async (req, res) => {
  try {
    await storageClient.ping();
    res.json({ status: 'ok', cache: 'reachable' });
  } catch (err) {
    res.status(503).json({ status: 'error', cache: 'unreachable' });
  }
});

Step 3: Heartbeat Monitoring for Scheduled Pipeline Runs

Many teams run a nightly full build to pre-warm the remote cache for the next morning's CI runs. If that pipeline silently fails, the first developer to push a PR will hit a cold cache and wait 10x longer than usual.

Set up a Vigilmon cron heartbeat to detect missed runs:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected interval to 1440 minutes (24 hours) for a nightly job.
3. Copy the heartbeat URL: https://vigilmon.online/heartbeat/abc123.
4. Add a curl call at the end of your pipeline script:

#!/bin/bash
set -e

# Run the full pipeline
npx turbo run build test lint --filter='...' 

# Signal successful completion to Vigilmon
curl -fsS https://vigilmon.online/heartbeat/abc123

In your CI configuration (GitHub Actions example):

name: Nightly cache warm-up
on:
  schedule:
    - cron: '0 2 * * *'  # 2 AM UTC

jobs:
  warm-cache:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx turbo run build test
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}
      - run: curl -fsS https://vigilmon.online/heartbeat/abc123

If the job fails before the curl step, or if the cron schedule itself is misconfigured, Vigilmon alerts after 24 hours without a ping.

Step 4: Track Cache Hit Rate Degradation via Webhooks

Turborepo outputs cache hit/miss statistics on every run. You can parse these and push alerts to Vigilmon when hit rates drop below an acceptable threshold.

Add a script to your monorepo root:

// scripts/check-turbo-cache.js
const { execSync } = require('child_process');

const CACHE_HIT_THRESHOLD = 0.5; // Alert if hit rate drops below 50%
const VIGILMON_WEBHOOK = process.env.VIGILMON_WEBHOOK_URL;

const output = execSync('npx turbo run build --dry=json 2>/dev/null', {
  encoding: 'utf8',
});

const result = JSON.parse(output);
const tasks = result.tasks || [];
const hits = tasks.filter(t => t.cache?.status === 'HIT').length;
const total = tasks.length;
const hitRate = total > 0 ? hits / total : 1;

console.log(`Cache hit rate: ${(hitRate * 100).toFixed(1)}% (${hits}/${total})`);

if (hitRate < CACHE_HIT_THRESHOLD && VIGILMON_WEBHOOK) {
  fetch(VIGILMON_WEBHOOK, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      event: 'cache_hit_rate_low',
      hit_rate: hitRate,
      hits,
      total,
    }),
  });
  process.exit(1);
}

Run this script in CI after every pipeline execution to catch cache regressions early:

- name: Check Turborepo cache health
  run: node scripts/check-turbo-cache.js
  env:
    VIGILMON_WEBHOOK_URL: ${{ secrets.VIGILMON_WEBHOOK_URL }}

Step 5: SSL Certificate Alerts for the Cache Server

If your self-hosted cache backend's SSL certificate expires, Turborepo clients will fail to connect and every CI build will time out waiting for a cache response that never arrives.

Add certificate monitoring in Vigilmon:

1. Open the HTTP monitor you created in Step 1.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

For Let's Encrypt-managed certs, a 21-day alert window gives ample time to investigate and fix auto-renewal failures before they affect CI. Renew manually if needed:

certbot renew --force-renewal -d turbocache.yourdomain.com
systemctl reload nginx

Step 6: Maintenance Windows During Cache Server Upgrades

When you upgrade turborepo-remote-cache or migrate storage backends, your cache endpoint will be temporarily unreachable. Suppress alerts with a Vigilmon maintenance window to avoid false positives:

# Open a 10-minute maintenance window before upgrading
MONITOR_ID="your-monitor-id"
API_KEY="your-vigilmon-api-key"

curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"monitor_id\": \"$MONITOR_ID\", \"duration_minutes\": 10}"

# Perform the upgrade
docker pull ghcr.io/ducktors/turborepo-remote-cache:latest
docker compose up -d --force-recreate

# Maintenance window expires automatically

Wire this into your upgrade runbook so the ops team doesn't need to manually suppress alerts during every cache maintenance event.

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP health check | /v8/artifacts/status on cache server | Cache server down, storage failure | | TCP port | Cache server :443 | TLS terminator or proxy down | | Cron heartbeat | Nightly pipeline URL | Missed warm-up run, CI cron failure | | SSL certificate | Cache server domain | Let's Encrypt renewal failure | | Webhook | Cache hit rate threshold | Cold cache due to configuration drift |

Turborepo's remote cache is invisible when it works and catastrophic when it doesn't — cold builds, backed-up CI queues, and frustrated developers. With Vigilmon monitoring the cache endpoint health, SSL certificates, and pipeline completion heartbeats, you'll catch cache failures in minutes rather than discovering them when your team's morning builds are already running slow.