references/observability/patterns.md
Observability Patterns
Use these decisions alongside the linked implementation guides. Application event schemas, billing policies, alert thresholds, and delivery behavior still need to be designed for the application.
| Task | Design decision and documentation | | --- | --- | | Usage-based billing | Define the billable event, tenant identity, time window, and accuracy requirements. Start with the maintained Analytics Engine billing recipe and sampling guidance; assess whether sampled estimates satisfy the billing contract. | | Performance monitoring | Use built-in metrics for aggregate health and traces to investigate dependency latency. Custom measurements need consistent units and aggregation semantics; check runtime timers before measuring CPU-only work. | | Error tracking | Emit structured context without secrets, investigate with Query Builder, and choose Tail Workers if custom alert processing is needed. Define thresholds and duplicate handling for your alert destination. | | Multi-tenant tracking | Choose the tenant dimension and consistent field positions using Analytics Engine get started and sampling guidance. Enforce tenant authorization in the application that exposes analytics; a dataset index is not an access-control boundary. | | Tail Worker filtering | Use the current Tail handler schema for outcomes, exceptions, and timing fields, with Tail configuration for producer wiring. Define filtering, redaction, and downstream failure handling for the destination. | | OpenTelemetry export | Prefer the maintained OTLP export integration for supported destinations. For Honeycomb, follow Export to Honeycomb instead of synthesizing spans from Tail events. |
Use Workers Logpush when the requirement is Workers Trace Event delivery to a supported log destination. Use a Tail Worker when custom processing is required beyond the configured export integration.