agentic-dev/docs/library-decisions/2026-05-14-@opentelemetry/sdk-node.md

package, version, tier, decision, date, deciders, adr, filter-results, verification-commands, accepted-cves

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

Filter: license

npm view @opentelemetry/sdk-node license returns Apache-2.0. Apache-2.0 is on the allowlist.

Filter: types

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

Filter: maintenance

Actively maintained by the OpenTelemetry community. The 0.55.x line is current and tracks the OTel JS SDK release cycle. sdk-node is the meta-package that wires together the trace, log, metric, and auto-instrumentation subsystems for Node.js.

Filter: boundary-fit

ADR-017 §8 restricts @opentelemetry/sdk-node to **/instrumentation/otel/** and app init paths. NodeSDK is instantiated once in core-shared/instrumentation/otel/init-otel-server-node.ts. Feature packages never instantiate or import it directly.

Filter: shadow-check

@opentelemetry/sdk-node is the standard Node.js OTel SDK meta-package. No competing OTel SDK bootstrapper is present in the workspace.

Filter: eu-residency

@opentelemetry/sdk-node is the SDK bootstrapper with no independent data transmission. All signals it routes pass through the configured exporters. EU residency is governed by the exporter DSN configuration.

Filter: cve-scan

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

Filter: named-consumer

packages/core-shared/src/instrumentation/otel/init-otel-server-node.ts uses NodeSDK to bootstrap the full OTel pipeline: resource detection, context propagation, trace/log/metric providers, SentrySpanProcessor, PiiScrubSpanProcessor, and all auto-instrumentation plugins (ADR-017).

Prompt: replaces

The former initSentryServerNode function which called Sentry SDK init methods directly. NodeSDK from sdk-node provides the unified bootstrapper that wires the complete OTel pipeline in a single sdk.start() call, replacing the need to manually construct and register each provider.

Prompt: migration-cost-out

Hard. NodeSDK is the single init entry point for the entire OTel server pipeline. Replacing it requires manually constructing and registering trace provider, log provider, metric provider, context manager, propagator, and all instrumentation plugins — essentially reimplementing what NodeSDK provides. The ITracer/ILogger/IMetrics boundaries (ADR-014/017) isolate feature code but the init layer itself is deeply coupled.

Prompt: alternatives-considered

1. Manual SDK assembly — Constructing TracerProvider, LoggerProvider, MeterProvider individually without NodeSDK. Rejected: high boilerplate; NodeSDK handles shutdown hooks, context manager registration, and propagator setup automatically.
2. @opentelemetry/auto-instrumentations-node — A higher-level meta-package that bundles many plugins. Rejected: includes instrumentations the workspace doesn't need; ADR-017 §11 specifies exactly which plugins to enable (http, undici, pg) for minimal scope.

See ADR-017 for the full decision rationale.