references/observability/gotchas.md
Observability Troubleshooting and Constraints
Missing or incomplete data
| Symptom | Check and authoritative guide | | --- | --- | | Logs missing from the dashboard | Confirm the deployed Worker/environment, collection and persistence settings, recent traffic, query time range, and sampling. Follow Workers Logs and Query Builder. | | Live logs differ from stored logs | Confirm which workflow is being inspected; live streams can sample under load. See real-time logs. | | Traces missing or incomplete | Check trace enablement and sampling separately from logs, then consult tracing setup and known limitations. | | Export destination has no data | Check signal type, destination name, credentials, endpoint compatibility, and provider status using OpenTelemetry export and, for a Worker, Workers OpenTelemetry export. For a Logpush job, use Workers Logpush. | | Tail consumer receives no events | Check the producer's consumer configuration and deployment using Tail Workers. | | Analytics Engine totals or averages look wrong | Account for sample weights and consistent field meanings using sampling guidance. Check limits for missing writes or expired data. | | Very short operations appear to take no time | Read performance and timers and trace limitations. Tracing does not eliminate the runtime's timing restrictions. |
Limits, retention, and cost
Fetch these pages when estimating cost or diagnosing truncation and missing data:
- Workers Logs: log size, retention, sampling, and pricing.
- Workers Traces and known limitations: availability, propagation, and instrumentation constraints.
- Workers pricing: current observability and Tail Worker billing terms.
- Analytics Engine limits and pricing: field/write limits, retention, query costs, and billing availability.
- Workers Logpush: Workers-specific eligibility, permissions, and pricing.
Sampling reduces coverage as well as volume. Do not interpret the absence of a sampled event as proof that an error did not happen. Keep required diagnostic context while avoiding credentials, full sensitive URLs, and unnecessary personal data in logs, custom dimensions, and exported records.