Observability
OpenTelemetry Trace Debugging Guide
Debug missing or incomplete OpenTelemetry traces by checking context propagation, sampling, exporters and service boundaries in order. This reference is written for developers who need practical validation behavior, reviewable rules and safe examples rather than copied snippets with no explanation.
Recommended workflow
| Step | Why it matters |
|---|---|
| Verify trace headers | Confirm traceparent reaches every HTTP, queue and worker boundary. |
| Inspect span creation | Check parent-child relationships, status and end timestamps before blaming the backend. |
| Check sampling | Head and tail sampling can intentionally remove traces or partial paths. |
| Follow the export path | Review SDK queues, collector logs and backend ingestion errors separately. |
Starter snippet
request -> trace context -> child spans -> collector -> exporter -> backendReview checks
- Keep service.name stable across deploys.
- Propagate context through async jobs explicitly.
- Redact secrets from span attributes.
- Measure dropped spans and exporter queue pressure.
Common mistakes
- Creating a new root span at every service.
- Recording full request bodies as attributes.
- Assuming a visible root span proves every child was exported.
Validation should help users correct input while protecting systems from bad data. Keep syntax checks, product policy, security review and deliverability checks separate.
Related Formalint references
Continue with Structured Logging Guide, Api Correlation Id Logging Guide, Application Health Check Guide.