Should I upgrade to OpenTelemetry JS 2.0 now?

Plan the upgrade from OpenTelemetry JS 1.x to 2.x when Node support floors and package defaults change, especially for teams with shared instrumentation libraries.

Keep shared libraries API-only and let each app own the SDK, unless you can raise every service and CI image to the new Node/TypeScript floors in one coordinated cutover.

Blockers

Who this is for

Candidates

App-owned NodeSDK 2.x cutover with aligned stable and experimental packages

OpenTelemetry JS SDK 2.0 was released as `v2.0.0` on March 17, 2025, and its official release notes require Node.js `^18.19.0 || >=20.6.0`, TypeScript `>=5.0.4`, and an ES2022 target. As of 2026-04-02, the guide says stable `1.x` SDK packages were supported for one year from the `2.0.0` release, so that support window has already passed. The 2.x generation splits package lines into stable `>=2.0.0` and unstable `>=0.200.0`, and the release notes explicitly say only experimental `0.200.0` packages are compatible with `v2.0.0`. If you rely on env-var autoconfiguration, the tracing release notes move `OTEL_TRACES_EXPORTER` and `OTEL_PROPAGATORS` handling out of low-level tracer providers and into `NodeSDK`.

When to choose

Use this when you can raise every production service and CI image to the new Node and TypeScript floors and want one supported baseline everywhere. It is the decisive choice if your apps currently depend on env-var-driven exporter and propagator setup, because 2.x keeps that behavior at the `@opentelemetry/sdk-node` layer rather than in low-level providers.

Tradeoffs

You get onto the current supported major and keep env-var autoconfiguration in the intended place, but you must upgrade runtime, compiler, and any direct SDK integrations together. Mixed stable `2.x` with old experimental `0.x` packages is not a supported combination.

Cautions

Refactors are required if your code uses removed or renamed SDK APIs such as `new Resource(...)`, `getEnv()`, `BasicTracerProvider.addSpanProcessor(...)`, `View`, `Aggregation`, `parentSpanId`, or `instrumentationLibrary`. Browser bootstrap code also cannot rely on `window.OTEL_*` anymore in 2.x.

Sources

Keep shared libraries API-only and leave SDK ownership to each application

The official upgrade guide says `@opentelemetry/api` and `@opentelemetry/semantic-conventions` are versioned independently and are not part of the JS SDK 2.x major. It also says that if your usage does not directly use the JS SDK 2.x packages, you most likely will not need code changes to migrate, aside from respecting the new minimum supported Node.js, TypeScript, and ES levels where relevant. The same guide notes that contrib packages are versioned independently and were not part of the JS SDK 2.0 release, which makes a thin shared-library contract safer than exporting SDK internals across repos. This pattern reduces churn for teams with multiple services and shared instrumentation helpers.

When to choose

Use this when you have shared instrumentation libraries in a monorepo or across multiple services and want to avoid forcing every consumer onto the same internal SDK surface at once. It is the decisive choice if your shared packages can expose only `@opentelemetry/api` contracts and semantic attributes while each application owns its SDK, exporters, resource detectors, and bootstrap.

Tradeoffs

This reduces cross-package breakage and lets services migrate on different schedules, but it limits what shared libraries can do for automatic bootstrap and exporter wiring. Application teams must own more setup code.

Cautions

Do not leak SDK-specific types from shared packages during the transition. The 2.x guide explicitly changed or removed several such types and classes, including `Resource`, detector interfaces, `View`, `MetricReader`-adjacent types, and `ReadableSpan.instrumentationLibrary`.

Sources

Facts updated: 2026-04-02
Published: 2026-04-03

Related questions

Try with your AI agent

$ npm install -g pocketlantern
$ pocketlantern init
# Restart Claude Code, Cursor, or your MCP client, then ask:
# "Should I upgrade to OpenTelemetry JS 2.0 now?"
Missing something? Request coverage