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 |
| verify-dependencies |
Verifying instrumentation packages and versions exist before adding them |
| 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 |
| capture-database-query-parameters |
Prepared-statement parameter capture per language (Java, .NET, Python, Node.js, Go) |
| 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.
The snippet below shows a complete span with attributes and status for Node.js — see nodejs for full setup including SDK initialisation, exporter configuration, and auto-instrumentation:
import { trace, SpanStatusCode } from '@opentelemetry/api';
const tracer = trace.getTracer('my-service', '1.0.0');
tracer.startActiveSpan('operation-name', async (span) => {
try {
span.setAttribute('user.id', userId);
span.setAttribute('order.id', orderId);
const result = await processOrder(orderId);
span.setAttribute('order.status', result.status);
span.setStatus({ code: SpanStatusCode.OK });
return result;
} catch (err) {
// Record the exception as a structured log record, not span.recordException — see rules/spans.md
span.setStatus({ code: SpanStatusCode.ERROR, message: `${err.name}: ${err.message}` });
const spanContext = span.spanContext();
logger.error('operation-name.failed', {
'trace_id': spanContext.traceId,
'span_id': spanContext.spanId,
'exception.type': err.name,
'exception.message': err.message,
'exception.stacktrace': err.stack,
});
throw err;
} finally {
span.end();
}
});
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
1---
2name: 'otel-instrumentation'
3description: Configures trace spans, defines custom metrics, sets up log exporters, and optimizes sampling strategies for OpenTelemetry instrumentation. Use when instrumenting applications with traces, metrics, or logs. Triggers on requests for observability, telemetry, tracing, metrics collection, logging integration, or OTel setup.
4license: Apache-2.0
5metadata:
6 source: https://skillmd.com/skills/dash0hq/otel-instrumentation
7 author: dash0
8 version: '2.0.0'
9 workflow_type: 'advisory'
10 supports-traces: "true"
11 supports-metrics: "true"
12 supports-logs: "true"
13---
14
15# OpenTelemetry Instrumentation Guide
16
17Expert guidance for implementing high-quality, cost-efficient OpenTelemetry telemetry.
18
19## Rules & Quick Reference
20
21| Use Case / Rule | Description |
22|-----------------|-------------|
23| [telemetry](./rules/telemetry.md) | **Entrypoint** — signal types, correlation, and navigation |
24| [resolve-values](./rules/resolve-values.md) | Resolving configuration values from the codebase |
25| [verify-dependencies](./rules/verify-dependencies.md) | Verifying instrumentation packages and versions exist before adding them |
26| [resources](./rules/resources.md) | Resource attributes — service identity and environment |
27| [k8s](./rules/platforms/k8s.md) | Kubernetes deployment — downward API, pod spec |
28| [spans](./rules/spans.md) | Spans — naming, kind, status, and hygiene |
29| [logs](./rules/logs.md) | Logs — structured logging, severity, trace correlation |
30| [metrics](./rules/metrics.md) | Metrics — instrument types, naming, units, cardinality |
31| [sensitive-data](./rules/sensitive-data.md) | Sensitive data — PII prevention, sanitization, redaction |
32| [capture-database-query-parameters](./rules/capture-database-query-parameters.md) | Prepared-statement parameter capture per language (Java, .NET, Python, Node.js, Go) |
33| [validation](./rules/validation.md) | Telemetry validation — post-deployment verification checklist |
34| [nodejs](./rules/sdks/nodejs.md) | Node.js instrumentation setup |
35| [go](./rules/sdks/go.md) | Go instrumentation setup |
36| [python](./rules/sdks/python.md) | Python instrumentation setup |
37| [java](./rules/sdks/java.md) | Java instrumentation setup |
38| [scala](./rules/sdks/scala.md) | Scala instrumentation setup |
39| [dotnet](./rules/sdks/dotnet.md) | .NET instrumentation setup |
40| [ruby](./rules/sdks/ruby.md) | Ruby instrumentation setup |
41| [php](./rules/sdks/php.md) | PHP instrumentation setup |
42| [browser](./rules/sdks/browser.md) | Browser instrumentation setup |
43| [nextjs](./rules/sdks/nextjs.md) | Next.js full-stack instrumentation (App Router) |
44
45## Official documentation
46
47- [OpenTelemetry Documentation](https://opentelemetry.io/docs/)
48- [Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/)
49- [Dash0 Integration Hub](https://www.dash0.com/hub/integrations)
50
51## Getting started
52
53Follow these steps when instrumenting an application from scratch:
54
551. **Pick your SDK rule** — choose the language-specific rule from the table above (e.g., [nodejs](./rules/sdks/nodejs.md), [python](./rules/sdks/python.md)).
562. **Set up resource attributes** — define service identity and environment per [resources](./rules/resources.md).
573. **Add spans, metrics, and logs** — instrument your code following [spans](./rules/spans.md), [metrics](./rules/metrics.md), and [logs](./rules/logs.md).
584. **Guard sensitive data** — scrub PII before export per [sensitive-data](./rules/sensitive-data.md).
595. **Validate** — confirm telemetry reaches the backend using the checklist in [validation](./rules/validation.md).
60
61The snippet below shows a complete span with attributes and status for Node.js — see [nodejs](./rules/sdks/nodejs.md) for full setup including SDK initialisation, exporter configuration, and auto-instrumentation:
62
63```js
64import { trace, SpanStatusCode } from '@opentelemetry/api';
65const tracer = trace.getTracer('my-service', '1.0.0');
66
67tracer.startActiveSpan('operation-name', async (span) => {
68 try {
69 span.setAttribute('user.id', userId);
70 span.setAttribute('order.id', orderId);
71
72 const result = await processOrder(orderId);
73
74 span.setAttribute('order.status', result.status);
75 span.setStatus({ code: SpanStatusCode.OK });
76 return result;
77 } catch (err) {
78 // Record the exception as a structured log record, not span.recordException — see rules/spans.md
79 span.setStatus({ code: SpanStatusCode.ERROR, message: `${err.name}: ${err.message}` });
80 const spanContext = span.spanContext();
81 logger.error('operation-name.failed', {
82 'trace_id': spanContext.traceId,
83 'span_id': spanContext.spanId,
84 'exception.type': err.name,
85 'exception.message': err.message,
86 'exception.stacktrace': err.stack,
87 });
88 throw err;
89 } finally {
90 span.end();
91 }
92});
93```
94
95## Key principles
96
97### Signal density over volume
98
99Every telemetry item should serve one of three purposes:
100- **Detect** - Help identify that something is wrong
101- **Localize** - Help pinpoint where the problem is
102- **Explain** - Help understand why it happened
103
104If it doesn't serve one of these purposes, don't emit it.
105
106### Sample in the pipeline, not the SDK
107
108Use the `AlwaysOn` sampler (the default) in every SDK.
109Do not configure SDK-side samplers — they make irreversible decisions before the outcome of a request is known.
110Defer all sampling to the [Collector](../otel-collector/rules/sampling.md), where policies can be changed centrally without redeploying applications.
111
112<!-- eval:skip -->
113```
114SDK (AlwaysOn) → Collector (sampling) → Backend (retention)
115 ↓ ↓ ↓
116 All spans Head or tail Storage policies
117 exported sampling applied
118```