# Observability and tracing

Read structured errors, durable audit records and Cloudflare spans as separate signals.

## Application errors and logs [#application-errors-and-logs]

The web middleware integrates evlog. Shared error codes and localized messages come from `packages/errors`; its server handler logs unexpected failures while the client resolver returns a safe user message. During development, inspect `.evlog/logs/` when available. Do not copy credentials, prompts or private payloads into logs.

Each RPC request has a request ID: `cf-ray` when Cloudflare set a well-formed one, otherwise a UUID. It is `context.requestId` on the server, the `x-request-id` header on every `/api/rpc` response (including the 500 when building the context fails), and a field of the error log. The MCP context derives its own `requestId` for the logs of its document tools; MCP responses do not carry the header. It serves only to correlate logs, never to decide anything: outside Cloudflare (local `wrangler dev`, Node) a client can send a well-formed `cf-ray` and it is used as is, and [Cloudflare's header reference](https://developers.cloudflare.com/fundamentals/reference/http-headers/) does not say whether a client-sent value is replaced. The error handler writes expected 4xx failures at debug level and unexpected ones (5xx, unknown codes, non-oRPC errors) as errors, both with the request ID, so a user's quoted header finds the matching line ([error handling](https://github.com/CarlosZiegler/autofolio/blob/main/docs/error-handling.md)).

An Audit Event is a durable domain record, not a log line. The Audit Log is the admin table; an Activity Timeline is one User's security history. Release notes belong to the public [changelog](/docs/changelog).

## Worker traces [#worker-traces]

Traces and invocation logs are off in `apps/web/wrangler.jsonc`. Both store each request's URL, and the buyer's passport link carries its token in the path (`/p/<token>`): a logged URL would open the passport, while the database keeps only the token's hash. Cloudflare applies these settings to the whole Worker, not to one path. Application logs stay on: evlog scrubs the token, plates, VINs, emails and amounts from them (`packages/errors/src/log-scrub.ts`).

The scheduled handler still passes `ctx.tracing` into `runScheduledJobs`; `workersTracer` adapts Effect spans to Cloudflare spans. It records scalar attributes, failures and interruption. Turning traces back on needs the token out of the URL first (for example, in the URL fragment, which no server receives).

The native API cannot assign an explicit parent to each Effect span. Those spans appear as siblings under `jobs.scheduled`, alongside platform fetch and Hyperdrive spans. Node execution runs without this tracer. Local successful jobs do not prove that production custom spans are visible in the Cloudflare dashboard.

## Diagnose a failure [#diagnose-a-failure]

Trace the entry point, transport result and durable row together. For an import, inspect its state and persisted failure reason before assuming the queue lost it. For a webhook, inspect the delivery lease and next attempt. For a client error, keep the stable error code and correlation context rather than exposing an exception message.

Bundle and fault experiments are recorded in `docs/measurements`. Their local timings are not production latency or billing measurements. Add a dated report when changing runtime ownership, deadlines or a heavy dependency.


## Key files [#key-files]

- [`packages/api/src/platform/rpc/request-id.ts`](https://github.com/CarlosZiegler/autofolio/blob/main/packages/api/src/platform/rpc/request-id.ts)
- [`packages/errors/src/server.ts`](https://github.com/CarlosZiegler/autofolio/blob/main/packages/errors/src/server.ts)
- [`packages/api/src/platform/effect/tracer.ts`](https://github.com/CarlosZiegler/autofolio/blob/main/packages/api/src/platform/effect/tracer.ts)
- [`packages/db/src/audit.ts`](https://github.com/CarlosZiegler/autofolio/blob/main/packages/db/src/audit.ts)
- [`apps/web/wrangler.jsonc`](https://github.com/CarlosZiegler/autofolio/blob/main/apps/web/wrangler.jsonc)