tutorial

Monitoring Nx Monorepos with Vigilmon

Nx powers large-scale monorepos with affected task computation, distributed task execution, and project graph analysis — but when the computation cache degrades or DTE workers stall, your CI throughput collapses. Here's how to monitor Nx build health with Vigilmon.

Nx is a smart, fast monorepo build system used by organizations running hundreds of projects in a single repository. Its computation caching, affected command analysis, and distributed task execution (DTE) can cut CI times by an order of magnitude — but when the Nx Cloud API is slow, cache hit rates collapse, or a flaky project graph invalidates too many tasks, you'll be the last to know. Vigilmon closes the observability gap: HTTP health checks on Nx Cloud connectivity, cron heartbeats on scheduled pipeline runs, and webhook alerts when cache performance degrades.

What You'll Set Up

  • HTTP health monitor for Nx Cloud or your self-hosted Nx cache backend
  • Affected task computation health via a custom API wrapper
  • Cron heartbeat for scheduled full-workspace builds
  • SSL certificate monitoring for self-hosted Nx cache servers
  • Maintenance windows for Nx Cloud migrations and agent upgrades

Prerequisites

  • Nx workspace (Nx 16+) with nx.json configured
  • Nx Cloud account or self-hosted Nx caching backend
  • CI pipeline running nx affected commands on pull requests
  • A free Vigilmon account

Step 1: Monitor the Nx Cloud API Endpoint

Nx Cloud is the primary remote cache and distributed execution backend for most Nx workspaces. If the API is unreachable, every task runs locally with no cache benefit and DTE falls back to single-agent mode.

Add a Vigilmon HTTP monitor:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter the Nx Cloud status endpoint: https://cloud.nx.app/api/v2/status or your self-hosted equivalent.
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

For self-hosted Nx caching (using @nrwl/nx-cloud in self-hosted mode or a compatible S3-backed solution), monitor your cache server's health endpoint directly:

https://nx-cache.yourdomain.com/health

If no health endpoint is available, use a TCP port monitor on port 443 to confirm the cache server is at least accepting connections.

Step 2: Expose Cache Health from a Self-Hosted Nx Backend

If you're running a self-hosted Nx cache compatible server, add an unauthenticated /health path that Vigilmon can probe:

// src/health.controller.ts (NestJS example)
import { Controller, Get } from '@nestjs/common';
import { CacheStorageService } from './cache-storage.service';

@Controller('health')
export class HealthController {
  constructor(private readonly storage: CacheStorageService) {}

  @Get()
  async check() {
    const storageOk = await this.storage.ping();
    if (!storageOk) {
      throw new Error('Storage backend unreachable');
    }
    return { status: 'ok', storage: 'reachable' };
  }
}

For an Express-based implementation:

app.get('/health', async (req, res) => {
  try {
    await s3Client.headBucket({ Bucket: process.env.CACHE_BUCKET }).promise();
    res.json({ status: 'ok', backend: 's3' });
  } catch (err) {
    res.status(503).json({ status: 'error', message: err.message });
  }
});

Vigilmon will hit this endpoint every minute. A 503 response fires an alert before your developers notice slow builds.

Step 3: Monitor Affected Task Computation Health

Nx's affected command determines which projects need to be rebuilt based on git changes. A misconfigured implicitDependencies, corrupted project graph, or git history issue can cause nx affected to incorrectly mark everything as affected — blowing up CI time.

Build a lightweight health check script that runs nx affected in dry-run mode and alerts when the affected count is anomalously high:

// scripts/check-nx-affected-health.js
const { execSync } = require('child_process');

const MAX_AFFECTED_PROJECTS = parseInt(process.env.MAX_AFFECTED_PROJECTS || '20');
const VIGILMON_WEBHOOK = process.env.VIGILMON_WEBHOOK_URL;

try {
  const output = execSync(
    'npx nx print-affected --type=app --select=projects 2>/dev/null',
    { encoding: 'utf8' }
  );
  const projects = output.trim().split(',').filter(Boolean);
  const count = projects.length;

  console.log(`Affected projects: ${count}`);

  if (count > MAX_AFFECTED_PROJECTS && VIGILMON_WEBHOOK) {
    fetch(VIGILMON_WEBHOOK, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        event: 'nx_affected_spike',
        affected_count: count,
        projects: projects.slice(0, 10), // first 10 for context
        threshold: MAX_AFFECTED_PROJECTS,
      }),
    });
    console.warn(`ALERT: ${count} affected projects exceeds threshold of ${MAX_AFFECTED_PROJECTS}`);
  }
} catch (err) {
  console.error('Failed to compute affected projects:', err.message);
  process.exit(1);
}

Run this in CI before the main build step:

- name: Check Nx affected health
  run: node scripts/check-nx-affected-health.js
  env:
    MAX_AFFECTED_PROJECTS: 30
    VIGILMON_WEBHOOK_URL: ${{ secrets.VIGILMON_WEBHOOK_URL }}

Step 4: Heartbeat Monitoring for Scheduled Full-Workspace Builds

Many Nx teams run a nightly full build (nx run-many --all) to pre-populate the computation cache and catch integration failures before the workday. If this pipeline silently fails, the next morning's nx affected runs will be slower and less reliable.

Configure a Vigilmon cron heartbeat:

  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set the expected interval to 1440 minutes (24 hours).
  3. Copy the heartbeat URL: https://vigilmon.online/heartbeat/xyz789.
  4. Add the ping call at the end of your nightly pipeline:
# .github/workflows/nightly-nx-build.yml
name: Nightly Nx full-workspace build
on:
  schedule:
    - cron: '0 1 * * *'  # 1 AM UTC

jobs:
  full-build:
    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
      - uses: nrwl/nx-set-shas@v4
      - run: npx nx run-many --target=build --all
        env:
          NX_CLOUD_AUTH_TOKEN: ${{ secrets.NX_CLOUD_AUTH_TOKEN }}
      - run: npx nx run-many --target=test --all
        env:
          NX_CLOUD_AUTH_TOKEN: ${{ secrets.NX_CLOUD_AUTH_TOKEN }}
      - name: Signal success to Vigilmon
        run: curl -fsS https://vigilmon.online/heartbeat/xyz789

If the build fails at any step, the curl call never runs and Vigilmon alerts after 24 hours with no ping received.

Step 5: SSL Certificate Alerts for Self-Hosted Cache

Self-hosted Nx cache servers use TLS to protect artifact integrity and auth tokens. An expired certificate breaks Nx Cloud agent connectivity silently — agents fall back to local execution without any error message in your build logs.

In Vigilmon:

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

Check certificate expiry manually at any time:

echo | openssl s_client -servername nx-cache.yourdomain.com \
  -connect nx-cache.yourdomain.com:443 2>/dev/null \
  | openssl x509 -noout -dates

Automate renewal with Let's Encrypt and verify the cron job is healthy:

# Test renewal without actually renewing
certbot renew --dry-run -d nx-cache.yourdomain.com

Step 6: Maintenance Windows for Nx Cloud Migrations

When upgrading Nx versions or migrating between cache backends, add a maintenance window in Vigilmon to suppress false-positive alerts during the transition:

MONITOR_ID="your-monitor-id"
API_KEY="your-vigilmon-api-key"

# Open a 15-minute window before starting the migration
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\": 15}"

# Run the migration
npx nx migrate latest
npx nx migrate --run-migrations

# Restart the cache server if self-hosted
systemctl restart nx-cache

# Window expires automatically — Vigilmon resumes monitoring

For major Nx version upgrades that require all CI agents to update simultaneously, set a longer 60-minute window.

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP health check | Nx Cloud API or self-hosted /health | Cache server down, storage failure | | TCP port | Cache server :443 | TLS or proxy down | | Cron heartbeat | Nightly full-build URL | Missed warm-up run, CI cron failure | | SSL certificate | Cache server domain | Certificate expiry breaking agent auth | | Webhook | Affected project count spike | Project graph corruption, dependency misconfiguration |

Nx makes large monorepos manageable — but its performance wins depend entirely on a healthy cache and a correct project graph. With Vigilmon monitoring the Nx Cloud endpoint, SSL certificates, and nightly build heartbeats, you'll catch cache failures before they cascade into slow CI queues and frustrated teams.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles