Instrumentation and auto-instrumentation

David Granzin By David Granzin

Instrumentation is the code that produces telemetry from an application. Auto-instrumentation adds it without changes to your code, by patching common libraries at startup; manual instrumentation is spans and metrics you write yourself.

Auto-instrumentation

Auto-instrumentation hooks into libraries your application already uses, such as the HTTP server, the HTTP client, the database driver and the queue client, and records spans and metrics for them. You add a package and a startup flag; your code does not change.

In Node.js, the auto-instrumentations package registers before your app loads:

npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node

export OTEL_SERVICE_NAME="checkout"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
node --require @opentelemetry/auto-instrumentations-node/register app.js

In Python, the distro installs instrumentation for the libraries it finds and wraps the start command:

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

export OTEL_SERVICE_NAME="checkout"
opentelemetry-instrument python app.py

How it works differs by language. Node.js and Python patch modules as they are loaded. Java uses a -javaagent that rewrites bytecode. .NET uses a profiler. Go compiles to a static binary, so its options are libraries you wire in yourself, compile-time instrumentation, or an eBPF agent that observes the process from outside.

What auto-instrumentation gives you, and what it does not

It covers the edges of each service: incoming requests, outgoing calls, database queries. That is enough for a service map, request rates, error rates, latency per route, and traces that cross services, because the HTTP instrumentation also propagates context.

It does not know your business logic. A checkout request appears as one server span with a database call and an HTTP call under it; the steps in between, such as pricing, fraud checks or inventory reservation, are invisible. It also cannot add attributes only your code knows, such as the order value or the customer's plan.

Manual instrumentation

Manual instrumentation fills that gap with the OpenTelemetry API: a span around an important function, an attribute with the tenant ID, a counter for orders placed. It works alongside auto-instrumentation, since manual spans become children of whatever span is active. See the span entry for an example.

A practical order: start with auto-instrumentation everywhere, look at a few traces of real requests, then add manual spans where the trace has a long gap with no explanation. Name custom attributes with a prefix you own, such as app.order.value, so they do not collide with the semantic conventions.

Costs to watch

Auto-instrumentation can produce more spans than you need: a span per Redis command in a loop, or per file system call. Most instrumentation packages let you disable individual libraries; turn off the noisy ones rather than sampling everything harder. Instrumentation also adds startup time and some overhead per request, usually small next to the network calls being measured.

Sources

오늘 첫 트레이스를 확인하세요.

SDK를 추가하고 OTLP 익스포터를 Maple로 향하게 하면 트레이스가 도착합니다.

maple.dev: OpenTelemetry 위의 옵저버빌리티