---
package: "@opentelemetry/instrumentation"
version: "^0.55.0"
tier: core
decision: approved
date: 2026-05-14
deciders: [Danijel Martinek]
adr: adr-017
filter-results:
  license: Apache-2.0
  types: native
  maintenance: active
  boundary-fit: pass
  shadow-check: pass
  eu-residency: n/a
  cve-scan: clean
  named-consumer: pass
  socketRisk: clean
verification-commands:
  - npm view @opentelemetry/instrumentation license
  - npm view @opentelemetry/instrumentation version
  - pnpm audit --audit-level=moderate
accepted-cves: []
---

## Filter: license

<!-- Result: Apache-2.0 -->

`npm view @opentelemetry/instrumentation license` returns `Apache-2.0`. Apache-2.0 is on the allowlist.

## Filter: types

<!-- Result: native -->

`@opentelemetry/instrumentation` is authored in TypeScript and ships its own `.d.ts` declaration files. No separate `@types/` package is needed.

## Filter: maintenance

<!-- Result: active -->

Actively maintained by the OpenTelemetry community as the base package for auto-instrumentation plugins. The 0.55.x line is current and tracks the SDK release cycle.

## Filter: boundary-fit

<!-- Result: pass -->

ADR-017 §11 enables auto-instrumentations (HTTP, undici, pg) in `initOtelServerNode`. `@opentelemetry/instrumentation` provides the base `InstrumentationBase` class and registration utilities required by all instrumentation plugins. It lives in `core-shared/instrumentation/otel/` init paths only.

## Filter: shadow-check

<!-- Result: pass -->

`@opentelemetry/instrumentation` is the standard OTel plugin infrastructure. No competing auto-instrumentation framework is present in the workspace.

## Filter: eu-residency

<!-- Result: n/a -->

`@opentelemetry/instrumentation` is a pure instrumentation framework with no network communication or data transmission. EU residency does not apply.

## Filter: cve-scan

<!-- Result: clean -->

`pnpm audit --audit-level=moderate` reports no advisories against `@opentelemetry/instrumentation` at the time of this trace.

## Filter: named-consumer

<!-- Result: pass -->

`packages/core-shared/src/instrumentation/otel/init-otel-server-node.ts` uses `@opentelemetry/instrumentation` to register the HTTP, undici, and pg instrumentation plugins (ADR-017 §11). These auto-instrumentations eliminate manual span creation for common I/O operations.

## Prompt: replaces

Manual span wrapping around HTTP calls, database queries, and fetch operations. `@opentelemetry/instrumentation` enables the auto-instrumentation plugins that patch Node.js built-ins and popular libraries to emit spans automatically, replacing boilerplate `tracer.startSpan()` calls.

## Prompt: migration-cost-out

Low. `@opentelemetry/instrumentation` is used only at SDK init time to register plugin instances. Removing it requires unregistering the auto-instrumentation plugins and optionally adding manual spans at call sites — a localized change in the init file.

## Prompt: alternatives-considered

1. **Manual span instrumentation only** — No auto-instrumentation base package needed, but every HTTP call and DB query would require explicit span wrapping. Rejected: high boilerplate cost, easy to miss call sites.
2. **DD-trace or other APM SDK** — Vendor-specific auto-instrumentation agents. Rejected in ADR-017: vendor lock-in; OTel auto-instrumentations achieve the same coverage with vendor-neutral output.

See ADR-017 for the full decision rationale.