Observability

Chapter 10. With the platform in place, one question remains — how does it see itself? Logs, metrics, and traces close Part III.

How the platform sees itself: logs, metrics, and traces — designed so the edge (a Worker, no Node) and the origin (a container) share the same conventions without sharing runtime. Packages: observability-core, observability, observability-edge, observability-tracing, plus edge-core/access-log.

The pipeline

The three signals

• Logs. observability-core holds the pure conventions both runtimes obey: a closed classifyError taxonomy (e.g. ECONNREFUSED/timeout → a category, never a raw message), a REDACT_KEYS set, and sanitizeReqId. The edge logs Workers-safe console-JSON (observability-edge); the origin logs with pino (observability), whose mixin() stamps the active span's trace_id/span_id onto every line. Same {lvl, svc, time, reqId} shape either side.

Edge code imports observability-edge only

Never import @ratio/observability (pino) into apps/edge / edge-core — pino pulls node:* deps that break on workerd. Use @ratio/observability-edge. This is caught only by a CI grep (a wrangler --dry-run on push to main) — your local typecheck/lint/test and PRs won't flag it.

• The edge access log — exactly one line per request with a fixed field allowlist (buildAccessLog): tenant, status, stale-flag, ms, pathname only — never the query string, no secrets.
• Metrics. buildMetricPoint emits one Analytics Engine point per request, keyed on tenant as the single index (the per-store error/stale/latency signal). data-db/metrics folds high-cardinality labels into _other.
• Traces. observability-tracing is off by default. When on: a ParentBasedSampler(TraceIdRatioBased) → BatchSpanProcessor → OTLP → SigNoz, with W3C propagation so a trace continues edge → origin → backend.

Redaction is structural, not best-effort

Errors are classified into a fixed taxonomy rather than logged raw, the access log has a field allowlist (not a denylist), and the query string is never logged. So a secret in a URL or an error string can't leak into a log line by accident. (ADR-0002.)