Standardize the evidence teams need without losing the meaning of each application. Validate trace relationships, data handling, and operations before expanding adoption.
Platform, infrastructure, and engineering enablement teams
Define the contract
Agree on task identity, operation names, environment, release, and safe user context across services.
Validate operations
Treat ingestion, retention, backup recovery, and upgrades as part of the observability service.
Roll out in stages
Prove one representative application and one failure mode before adding more workloads.
At a glance
| Platform responsibility | Acceptance evidence |
|---|---|
| Instrumentation contract | Consistent IDs, environment, release, and parent relationships |
| Data handling | Approved transformation tested on realistic payloads |
| Telemetry reliability | Known behavior during failure, retry, and shutdown |
| Deployment | A demonstrated restore and documented upgrade path |
| Adoption | An application team resolves a real incident |
Define a small, useful instrumentation contract
Lunary documents SDK instrumentation and OpenTelemetry ingestion. For a shared platform, specify the attributes that make traces comparable: application, environment, release, task identifier, operation type, and the relationship between parent and child runs. Keep application-specific detail in structured metadata rather than inventing a different top-level convention for every team. Test the mapping against actual exported spans; similar names do not guarantee equivalent semantics.
Make payload handling explicit
Prompts, tool inputs, and outputs can contain more information than a conventional request log. Decide which fields are needed for debugging, how they are transformed before transmission, and who can access them. Test redaction with nested and structured payloads. Verify that the remaining context still explains a failure. Include exports and support workflows in the data review, not only the initial ingestion endpoint.
Observe the observability path
Define how the team detects missing, delayed, or duplicate telemetry. Exercise a network failure and runtime shutdown in a non-production environment. Compare application task counts with recorded runs over a bounded interval and account for sampling rules. Keep provider outages separate from ingestion outages so an empty chart does not create a false impression of a healthy application.
Evaluate the deployment as an operated service
Lunary publishes Docker Compose and other self-hosting guidance. Review the architecture and feature availability for the deployment you intend to use, then demonstrate backup restoration and upgrade procedures. For managed deployment, review the corresponding data controls and commercial terms. The acceptance criterion is a service your team knows how to maintain, not a container that starts once.
Make adoption and exit measurable
Start with one application whose team can verify the traces. Preserve existing instrumentation while comparing a bounded workload, and document any field mapping differences. Define the exit path at the same time: what can be exported, how IDs remain usable, and which objects need separate migration. Roll out a standard integration only after users can diagnose a real incident with it.
- Verify nested traces across service or worker boundaries.
- Reconcile task counts and known sampling decisions.
- Test an export with a representative failure and structured payload.
- Document ownership for upgrades, backups, and ingestion incidents.
Common questions
Can OpenTelemetry eliminate all integration work?
No. It can provide a common transport and instrumentation foundation, but you still need to validate attribute mapping, context propagation, and application-specific meaning.
Does self-hosting automatically satisfy every security requirement?
No. Requirements depend on deployment configuration, access, operations, and the organization's policies. Verify the specific controls you need.
What is a good first rollout target?
Choose a representative application with a clear owner, known failure cases, and a team ready to compare its own task counts with the recorded telemetry.
Sources & methodology
Lunary publishes this guide. We compare documented workflows and explain where each approach fits; this is not an independent benchmark or a hands-on product rating. Features, limits, and commercial terms can change. Check the linked vendor documentation before deciding.