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

Use Case	Rule
Node.js backend	nodejs
Go backend	go
Python backend	python
Java backend	java
Scala backend	scala
.NET backend	dotnet
Ruby backend	ruby
PHP backend	php
Browser frontend	browser
Next.js (App Router)	nextjs
Kubernetes pod spec	k8s
Resolve config values	resolve-values
Resource attributes	resources
Writing metrics	metrics
Cardinality management	metrics
Span naming, kind, status	spans
Writing logs	logs
Signal overview	telemetry