error-pipeline

name: error-pipeline description: >- Per-site client tracker and Astro endpoint for the centralised soborbo-error-pipeline workers. Captures client JS errors via sendBeacon, forwards via console.error → Tail Worker. Server-side uncaught exceptions are captured automatically. ~1.5KB client bundle, no external deps. Email throttled to 1 per (site, code) per 4 hours by the notifier worker.

Error Pipeline Skill

When To Use

Astro project on Cloudflare Workers needs error monitoring
The soborbo-error-pipeline repo is already deployed
Project should report client errors and have server exceptions captured

When Not To Use

Heavy frontend (React/Vue SPA) — tracker is tuned for static + island Astro
Pre-launch / staging — only wire this in when you want alerts

Architecture

producer Astro project           shared infra (separate repo)
┌──────────────────┐             ┌──────────────────────┐
│ tracker.ts       │ sendBeacon  │ error-notifier       │
│ ~1.5KB client    │────────────►│ (Tail Worker)        │
│                  │             │   ↓                  │
│ /api/error-log   │ tail_consumer  ERROR_KV ──┐        │
│ 15-line endpoint │────────────►│   ↓         │        │
│                  │             │   Resend    │        │
│ + auto SSR       │             │   CRITICAL  │        │
│   exception cap  │             └─────────────┼────────┘
└──────────────────┘                           ▼
                                         error-admin
                                       (Cloudflare Access)

Producer is dumb on purpose. Endpoint logs structured JSON via console.error and returns 204 immediately. All severity, throttling, persistence, and email logic lives in the notifier worker.

File Structure

src/
├── lib/errors/
│   ├── tracker.ts          # client tracker, sendBeacon
│   └── client-init.ts      # global handlers + init
└── pages/api/
    └── error-log.ts        # 15-line endpoint, returns 204

Quick Setup

Copy reference files into src/lib/errors/ and src/pages/api/.
Wire the client init in your base layout (last script before </body>):

<script>
  import { initErrorTracker } from '@/lib/errors/client-init';
  initErrorTracker({
    siteId: import.meta.env.PUBLIC_SITE_ID || 'unknown',
    endpoint: '/api/error-log',
  });
</script>

Set PUBLIC_SITE_ID to match the producer's wrangler.jsonc script name.

Add to wrangler.jsonc:

{ "tail_consumers": [{ "service": "error-notifier" }] }

Redeploy.

Reporting From Server Code

Uncaught exceptions: do nothing — Workers captures these automatically.

Known error conditions in API routes:

console.error(JSON.stringify({
  __pipeline: 'error',
  code: 'EMAIL-BOTH-001',
  message: 'Resend and Brevo both failed',
  url: request.url, source: '/api/quote',
  context: { resendStatus: 500 },
  stack: '', ts: new Date().toISOString(),
  requestId: crypto.randomUUID().slice(0, 12),
  fingerprint: 'EMAIL-BOTH-001:quote',
  pageLoadedAgo: 0,
  userAgent: '', viewport: '', connection: '', sessionId: '',
}));

The notifier resolves severity from the code.

Performance

Client init runs in requestIdleCallback — ~0.3-0.5ms TTI cost
Bundle ~1.5KB minified, no dependencies
sendBeacon is fire-and-forget — zero blocking
Endpoint returns 204 in <5ms, no awaits

What This Skill Does NOT Cover

Web Vitals (separate skill, different alerting model)
Source map upload (manual; add to deploy script if needed)
The notifier/admin workers — see soborbo-error-pipeline repo