| name | otel-instrumentation |
| description | Expert guidance for emitting high-quality, cost-efficient OpenTelemetry telemetry. Use when instrumenting applications with traces, metrics, or logs. Triggers on requests for observability, telemetry, tracing, metrics collection, logging integration, or OTel setup. |
| license | MIT |
| metadata | {"author":"dash0","version":"2.0.0","workflow_type":"advisory","signals":["traces","metrics","logs"]} |
OpenTelemetry Instrumentation Guide
Expert guidance for implementing high-quality, cost-efficient OpenTelemetry telemetry.
Rules
| Rule | Description |
|---|
| telemetry | Entrypoint - signal types, correlation, and navigation |
| resolve-values | Resolving configuration values from the codebase |
| resources | Resource attributes - service identity and environment |
| k8s | Kubernetes deployment - downward API, pod spec |
| spans | Spans - naming, kind, status, and hygiene |
| logs | Logs - structured logging, severity, trace correlation |
| metrics | Metrics - instrument types, naming, units, cardinality |
| nodejs | Node.js instrumentation setup |
| go | Go instrumentation setup |
| python | Python instrumentation setup |
| java | Java instrumentation setup |
| scala | Scala instrumentation setup |
| dotnet | .NET instrumentation setup |
| ruby | Ruby instrumentation setup |
| php | PHP instrumentation setup |
| browser | Browser instrumentation setup |
| nextjs | Next.js full-stack instrumentation (App Router) |
Official documentation
Key principles
Signal density over volume
Every telemetry item should serve one of three purposes:
- Detect - Help identify that something is wrong
- Localize - Help pinpoint where the problem is
- Explain - Help understand why it happened
If it doesn't serve one of these purposes, don't emit it.
Sample in the pipeline, not the SDK
Use the AlwaysOn sampler (the default) in every SDK.
Do not configure SDK-side samplers — they make irreversible decisions before the outcome of a request is known.
Defer all sampling to the Collector, where policies can be changed centrally without redeploying applications.
SDK (AlwaysOn) → Collector (sampling) → Backend (retention)
↓ ↓ ↓
All spans Head or tail Storage policies
exported sampling applied
Quick reference
