packages/error-reporter/README.md

1# Error Reporter
2
3This private Worker implements Cloudflare OS's vendor-neutral `ErrorReporter` RPC contract. The bundled implementation writes each bounded issue event as one structured `console.error()` object, which [Workers Logs](https://developers.cloudflare.com/workers/observability/logs/workers-logs/) indexes without an external SDK.
4
5That console call is a demonstration of the collection path, not the intended end state. It gives every deployment a working, queryable destination before anyone picks a collector. Replace it once you know where exception events should live.
6
7The Workshop binding supplies trusted `service`, `environment`, and optional `release` metadata. A report looks like:
8
9```json
10{
11  "event": "error_report",
12  "service": "cloudflare-os-workshop",
13  "environment": "production",
14  "release": "abc123",
15  "schemaVersion": 1,
16  "occurrenceId": "...",
17  "occurredAt": "...",
18  "failureSite": "overseer.run-agent",
19  "severity": "error",
20  "handled": false,
21  "exception": { "type": "Error", "message": "...", "stack": "..." }
22}
23```
24
25This is an issue destination, not a catch-all. Uncaught Worker failures remain in the producing Worker's logs; only explicit upstream `reportIssue()` calls arrive here.
26
27## Replace the destination
28
29Keep the `ErrorReporter` entrypoint and the `report(event)` signature. Everything inside `report()` is yours, and producers need no change because the bindings and the bounded event contract stay the same.
30
31Things the replacement usually does:
32
33- POST the event to an exception collector such as Sentry, grouped by `failureSite` and `exception.type`.
34- Attach `release` so the destination can symbolicate the stack against the matching source maps.
35- Route by severity, paging on unhandled `error` events and filing the rest.
36- Drop or sample noisy `failureSite` values before they reach a per-event billing plan.
37
38Wrap the transport in `try`/`catch` so a destination outage never reaches the caller. Reporting stays best-effort and private: never add secrets, prompts, tokens, headers, or request/response bodies to exceptions or attributes.
39
40See [Observability and error reporting](../../docs/observability.md) for deployment controls, triage, browser reporting, source maps, and external export options.
41
42## Check
43
44```sh
45pnpm run test:run
46pnpm run types:check
47pnpm exec wrangler deploy --dry-run
48```
49