| name | otel-instrumentation |
| description | Configures OpenTelemetry trace spans, metrics, and log exporters. Use ONLY when instrumenting applications specifically with OpenTelemetry (OTel). Triggers on requests explicitly mentioning OpenTelemetry, OTel, or OTLP. |
| license | MIT |
| metadata | {"author":"dash0","version":"2.0.0","workflow_type":"advisory","supports-traces":"true","supports-metrics":"true","supports-logs":"true"} |
OpenTelemetry Instrumentation Guide
Expert guidance for implementing high-quality, cost-efficient OpenTelemetry telemetry.
Rules & Quick Reference
| Use Case / 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 |
| sensitive-data | Sensitive data — PII prevention, sanitization, redaction |
| validation | Telemetry validation — post-deployment verification checklist |
| 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
Getting started
Follow these steps when instrumenting an application from scratch:
- Pick your SDK rule — choose the language-specific rule from the table above (e.g., nodejs, python).
- Set up resource attributes — define service identity and environment per resources.
- Add spans, metrics, and logs — instrument your code following spans, metrics, and logs.
- Guard sensitive data — scrub PII before export per sensitive-data.
- Validate — confirm telemetry reaches the backend using the checklist in validation.
When activated, you MUST use the Read tool to read the relevant rule file from the table above before providing guidance.
Output Format
When providing instrumentation guidance, strictly follow this structure:
- Required Packages: List dependencies to install.
- Configuration: Required environment variables.
- Implementation: Code snippets for initialization and custom spans.
- Validation: How to verify the telemetry is exported.
Do not include conversational filler.
Delegation
- If the user asks to instrument an entire codebase or multiple services, use the
Task tool (subagent) to explore the codebase or apply instrumentation in parallel across services.
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
