1. Blog
  2. OpenTelemetry JavaScript SDK 3.0: What Changed and How to Migrate Your Node.js Tracing
Blog

OpenTelemetry JavaScript SDK 3.0: What Changed and How to Migrate Your Node.js Tracing

OTel JS SDK 3.0 needs Node.js 22.15+, merges the tracing packages, drops Jaeger and makes logs stable. What changed and how to migrate your Node.js setup from 2.x.

The Atatus TeamPublished November 13, 202612 min read
OpenTelemetry JavaScript SDK 3.0: What Changed and How to Migrate Your Node.js Tracing

OpenTelemetry JavaScript SDK 3.0 is out. The stable SDK packages moved to 3.x, the experimental ones to 0.300.x, and the API to 1.10.0, all published on 20 October 2026. For a Node.js service, four changes matter most: Node.js 22.15 or later is now required, the three tracing SDK packages became one package, @opentelemetry/sdk-trace, the Jaeger exporter and propagator are gone, and logs are stable, with the Logs API now part of @opentelemetry/api.

How much work the upgrade takes depends on how you set OpenTelemetry up. If you start it with @opentelemetry/auto-instrumentations-node and environment variables, you upgrade Node.js and the packages, and your code stays the same. If you build the SDK in code with NodeTracerProvider, span processors or a Jaeger exporter, you have code to change. This guide covers both cases, then shows how to send traces, metrics and logs from the upgraded SDK to Atatus.

Table of Contents

What's new in OpenTelemetry JS SDK 3.0

"SDK 3.x" is the name for the new releases of the @opentelemetry/* packages built in the opentelemetry-js repository, apart from the API and semantic conventions packages. Stable packages are now 3.x and experimental packages 0.300.x. The jump from 0.223 to 0.300 is deliberate, so you can tell which experimental releases belong with SDK 3. The API package had a minor release, 1.10.0, with no breaking changes, and the semantic conventions package didn't change.

ChangeWhat it means for a Node.js service
Node.js >=22.15.0Node.js 18 and 20 are no longer supported. Node.js 20 reached end-of-life in April 2026. The API and semantic conventions packages keep their older minimums.
Proper ESM and CommonJS exportsImports by package name work as before. Imports of files inside a package (deep imports) break, because every package now lists its entry points in the exports field.
One tracing SDK packagesdk-trace-base, sdk-trace-node and sdk-trace-web are replaced by @opentelemetry/sdk-trace. NodeTracerProvider becomes TracerProvider, and register() is gone.
Logs are stableThe Logs API moved into @opentelemetry/api, and @opentelemetry/api-logs was removed. @opentelemetry/sdk-logs is now a stable 3.x package.
Deprecated packages removedThe Jaeger exporter and propagator and the OpenTracing and OpenCensus shims are gone.
Complex attribute valuesSpan and log record attributes can hold objects, null and mixed arrays. Resource and metric attributes still take simple values only.

At the time of writing, the latest releases are 3.1.1 for stable packages and 0.301.2 for experimental ones. @opentelemetry/auto-instrumentations-node moved to SDK 3 in version 0.82.0. The 2.x stable packages will be supported for one year from the 3.0.0 release, so you have time to plan the upgrade, but not to skip it. The official SDK 3.0 announcement explains why the project made these changes.

Who has to change code

  • Zero-code setup. If you load @opentelemetry/auto-instrumentations-node/register through NODE_OPTIONS and configure everything with OTEL_* environment variables, the OpenTelemetry project says you don't need to change code. Move to Node.js 22.15 or later and upgrade the package to 0.82.0 or later. The one setting to check is OTEL_PROPAGATORS: jaeger is no longer recognized, so it's skipped with a warning.
  • NodeSDK in a setup file. If you create NodeSDK in your own telemetry.js, expect a few small changes. The singular spanProcessor, metricReader and logRecordProcessor options are gone, the namespace re-exports such as tracing and resources are gone, and imports from sdk-trace-base move to sdk-trace.
  • A tracer provider built by hand. If you create NodeTracerProvider or BasicTracerProvider yourself, you have the most to change: the class name, the span processor constructors, the register() call and any sampler or limit settings you read from environment variables.
  • Bundled server code. If you bundle your Node.js service with webpack, esbuild, Rollup or Vite, the bundler must support the imports and exports fields in package.json and resolve the node condition. Otherwise the bundle can contain the browser build of the SDK.

Breaking changes checklist

Go through this list against your setup code and package.json. Each item names what to look for and what to use instead.

  • Node.js below 22.15.0. Upgrade the runtime before anything else. Every SDK 3.x package declares "node": ">=22.15.0".
  • Deep imports. Paths such as @opentelemetry/core/build/src/... now fail with ERR_PACKAGE_PATH_NOT_EXPORTED. Import from the package name. <package>/package.json can't be imported either, so read the SDK version from SDK_INFO in @opentelemetry/core.
  • @opentelemetry/sdk-trace-base, sdk-trace-node or sdk-trace-web in your dependencies. Replace them with @opentelemetry/sdk-trace. BasicTracerProvider, NodeTracerProvider and WebTracerProvider all become TracerProvider.
  • provider.register(). Removed. Set the global tracer provider, context manager and propagator yourself, as shown in the migration steps.
  • new BatchSpanProcessor(exporter, options). Span processors now take one options object: new BatchSpanProcessor({ exporter, ...options }). The same applies to SimpleSpanProcessor.
  • Sampler, batch and limit environment variables with a manual provider. sdk-trace no longer reads OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG, the OTEL_BSP_* variables or the attribute and span limit variables. Pass these values in code, or use NodeSDK, which still reads them.
  • @opentelemetry/exporter-jaeger. Removed. Use an OTLP exporter. Jaeger accepts OTLP natively, so you can point the exporter at Jaeger's OTLP port.
  • @opentelemetry/propagator-jaeger or OTEL_PROPAGATORS=jaeger. Removed. Use W3CTraceContextPropagator. Every service that sends or receives trace context has to switch, or traces break at the services that haven't.
  • @opentelemetry/shim-opentracing or shim-opencensus. Removed. Move that instrumentation to the OpenTelemetry API first. The background is in OpenTelemetry vs OpenTracing.
  • @opentelemetry/api-logs. Removed. Import logs and SeverityNumber from @opentelemetry/api.
  • AsyncHooksContextManager. Removed. Use AsyncLocalStorageContextManager from the same package, @opentelemetry/context-async-hooks.
  • Singular options on NodeSDK. spanProcessor, metricReader and logRecordProcessor are removed. Use the array options spanProcessors, metricReaders and logRecordProcessors. traceExporter still works.
  • Namespace imports from @opentelemetry/sdk-node. api, contextBase, core, logs, metrics, resources, node and tracing are no longer re-exported. Import from the real packages.
  • forceFlushTimeoutMillis. Removed from TracerProvider options. Pass it at call time: provider.forceFlush({ timeoutMillis: 5000 }).
  • Objects or arrays of mixed types in resource attributes. They're dropped with a warning. Keep resource attributes to strings, numbers, booleans and arrays of one of those types.
  • serverName on HttpInstrumentation. Removed. It had no effect, so delete it.
  • PrometheusExporter exposed to other hosts. It now binds to localhost by default and no longer reads its host and port variables. Pass host and port to the constructor if something else scrapes it.
  • Bundlers. webpack needs 5.54 or later, Jest 29.4 or later and React Native's Metro 0.81.3 or later. For a server bundle, make sure the node condition is applied: esbuild platform: 'node', a Node.js webpack target, or node in Rollup's exportConditions.

The official 3.x migration guide lists every change, including ones that only affect browser code and SDK authors.

Migrating from 2.x, step by step

1. Move to Node.js 22.15 or later

Check the version in every place your service runs, not only on your laptop: the Docker base image, the CI image and the serverless runtime.

node --version   # must print v22.15.0 or later

If a service can't move off Node.js 20 yet, keep it on SDK 2.x for now. Mixing is fine across services, because they only share trace context over the wire. Within one service, all OpenTelemetry packages have to come from the same generation.

2. Prepare while you're still on 2.x

Two changes are easier to make before the version bump, because you can ship and test them on their own:

  • Switch to @opentelemetry/sdk-trace. The new package already exists in the 2.x line, from 2.9.0. Moving your imports to it and fixing deprecation warnings now makes the 3.x upgrade smaller.
  • Finish any Jaeger-to-W3C propagation move. If your services pass uber-trace-id headers, run both propagators side by side with CompositePropagator until every service reads and writes traceparent. Do this on 2.x: propagator-jaeger@2 needs @opentelemetry/api below 1.10, so it can't be installed next to SDK 3.

If you still export to Jaeger, switch from JaegerExporter to an OTLP exporter at this point too. The same change is shown with SDK 3 imports in step 4.

3. Upgrade every OpenTelemetry package together

SDK 2.x packages require @opentelemetry/api below 1.10.0, and SDK 3.x packages require 1.10.x. Upgrading one package at a time gives you peer dependency errors or two copies of the API, so bump them in one go and remove the packages that no longer exist:

npm install @opentelemetry/api@^1.10.0 \
  @opentelemetry/sdk-node@^0.301.2 \
  @opentelemetry/auto-instrumentations-node@^0.83.1 \
  @opentelemetry/exporter-trace-otlp-proto@^0.301.2

npm uninstall @opentelemetry/sdk-trace-base @opentelemetry/sdk-trace-node \
  @opentelemetry/api-logs @opentelemetry/exporter-jaeger @opentelemetry/propagator-jaeger

Add any other @opentelemetry/* packages you use to the first command: stable ones such as sdk-trace, sdk-metrics and sdk-logs at ^3.1.1, experimental ones such as the OTLP exporters at ^0.301.2. If you export over gRPC, use 0.301.2 or later, which stops the gRPC exporter from loading @grpc/grpc-js before the instrumentations can wrap net and dns.

Then check that only one version of the API is installed:

npm ls @opentelemetry/api

Every entry should show 1.10.x. An older copy usually means a dependency still pins an SDK 2.x package.

4. Update your setup code

If you build the tracer provider by hand, this is the main change. A typical 2.x setup:

// telemetry.js (SDK 2.x)
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');
const { resourceFromAttributes } = require('@opentelemetry/resources');

const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({ 'service.name': 'checkout-api' }),
  spanProcessors: [
    new BatchSpanProcessor(new OTLPTraceExporter(), { maxQueueSize: 4096 }),
  ],
});
provider.register();

The same setup on SDK 3.x. The provider comes from @opentelemetry/sdk-trace, the span processor takes one options object, and the three globals that register() used to set are set explicitly:

// telemetry.js (SDK 3.x)
const { context, propagation, trace } = require('@opentelemetry/api');
const { TracerProvider, BatchSpanProcessor } = require('@opentelemetry/sdk-trace');
const { AsyncLocalStorageContextManager } = require('@opentelemetry/context-async-hooks');
const {
  CompositePropagator,
  W3CTraceContextPropagator,
  W3CBaggagePropagator,
} = require('@opentelemetry/core');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');
const { resourceFromAttributes } = require('@opentelemetry/resources');

const provider = new TracerProvider({
  resource: resourceFromAttributes({ 'service.name': 'checkout-api' }),
  spanProcessors: [
    new BatchSpanProcessor({ exporter: new OTLPTraceExporter(), maxQueueSize: 4096 }),
  ],
});

// register() is gone: set the tracer provider, context manager and propagator yourself
trace.setGlobalTracerProvider(provider);
context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());
propagation.setGlobalPropagator(
  new CompositePropagator({
    propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()],
  })
);

Without the context manager, spans created in callbacks and after await lose their parent and show up as separate traces. Without the propagator, outgoing requests carry no traceparent header and traces stop at the service boundary.

This provider also no longer reads OTEL_TRACES_SAMPLER or the OTEL_BSP_* variables. If you set a sampling ratio that way, pass a sampler in code:

const { ParentBasedSampler, TraceIdRatioBasedSampler } = require('@opentelemetry/sdk-trace');

const provider = new TracerProvider({
  sampler: new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(0.25) }),
  // ...resource and spanProcessors as above
});

If you use NodeSDK, the changes are smaller. Replace the singular options with arrays:

// before
const sdk = new NodeSDK({
  spanProcessor: new SimpleSpanProcessor({ exporter }),
  metricReader: new PeriodicExportingMetricReader({ exporter: metricExporter }),
});

// after
const sdk = new NodeSDK({
  spanProcessors: [new SimpleSpanProcessor({ exporter })],
  metricReaders: [new PeriodicExportingMetricReader({ exporter: metricExporter })],
});

Replace namespace imports from sdk-node with direct ones, for example import { resourceFromAttributes } from '@opentelemetry/resources' instead of resources.resourceFromAttributes. If you still had JaegerExporter, swap it for OTLPTraceExporter and point it at an OTLP endpoint, such as Jaeger's own OTLP port:

// before
const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
new BatchSpanProcessor({
  exporter: new JaegerExporter({ endpoint: 'https://collector.example.com:14268/api/traces' }),
});

// after
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');
new BatchSpanProcessor({
  exporter: new OTLPTraceExporter({ url: 'https://collector.example.com:4318/v1/traces' }),
});

5. Start the service and verify

  • Load the SDK before your app. For CommonJS, start with node --require ./telemetry.js app.js. For an ESM app, the loader hook is still needed: node --experimental-loader=@opentelemetry/instrumentation/hook.mjs --import ./telemetry.mjs app.js. If the SDK starts too late, libraries get no-op tracers and nothing is recorded.
  • Read the startup warnings. SDK 3 warns when it skips a propagator name it doesn't know or drops a complex resource attribute.
  • Check one request end to end. Send a request that crosses two services and confirm the spans arrive as a single trace with the database and HTTP calls inside it. A trace that splits in two at a service boundary points to a propagator problem.
  • ERR_PACKAGE_PATH_NOT_EXPORTED at startup means some code, often an older helper library, imports a file inside an OpenTelemetry package. Change it to import from the package name.

What stable logs means for Node.js

With 3.0, traces, metrics and logs are all stable in OpenTelemetry JavaScript. In practice:

  • The Logs API lives in @opentelemetry/api. logs and SeverityNumber are imported from the same package as trace and metrics, with the same stability promise. The separate @opentelemetry/api-logs package is gone.
  • @opentelemetry/sdk-logs is stable. It jumped from 0.x to 3.x, so its LoggerProvider and log record processors follow the same semantic versioning as the tracing and metrics SDKs.
  • Some pieces are still experimental. The OTLP log exporters, like all OTLP exporters, and @opentelemetry/sdk-node are still 0.x packages, so they can still change in a minor release.
  • Log records can carry structured attributes. Log record attributes accept complex values such as nested objects, so structured log fields don't have to be flattened into strings.

Most applications never call the Logs API directly. The pino, winston and bunyan instrumentations in auto-instrumentations-node do two things with your existing logger: they add the active trace ID and span ID to each log record, and they send the record to the OpenTelemetry Logs SDK. That way a log line written during a request carries the ID of the trace it belongs to. Sending works with pino 7 and later and winston 3. Winston also needs the @opentelemetry/winston-transport package installed.

If you do write logs through the API, only the import changes:

// before: const { logs, SeverityNumber } = require('@opentelemetry/api-logs');
const { logs, SeverityNumber } = require('@opentelemetry/api');

const logger = logs.getLogger('billing');
logger.emit({
  severityNumber: SeverityNumber.WARN,
  severityText: 'WARN',
  body: 'Card declined',
  attributes: { 'payment.provider': 'stripe', 'payment.retry': 2 },
});

A few type and option names changed with the move. LogAttributes and AnyValueMap become Attributes, and LogBody becomes AnyValue, both from @opentelemetry/api. logs.setGlobalLoggerProvider() now returns a boolean instead of the provider. In @opentelemetry/sdk-logs, LoggerConfig.disabled became enabled, SdkLogRecord became ReadWriteLogRecord, and LoggerProviderConfig became LoggerProviderOptions.

Sending OpenTelemetry traces, metrics and logs to Atatus

Atatus receives OTLP over HTTP at https://otel-rx.atatus.com, in protobuf or JSON, and the SDK 3.x exporters work with it unchanged. Requests are authenticated with an api-key header. You'll find the key in the Atatus dashboard under Settings → Account Settings → API Keys. Use the HTTP exporters, which are the SDK default (http/protobuf), rather than gRPC.

Option 1: no code changes

Install the API and the auto-instrumentation package, set the exporter variables and start your app with the register hook:

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

export OTEL_SERVICE_NAME="checkout-api"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-rx.atatus.com:443"
export OTEL_EXPORTER_OTLP_HEADERS="api-key=YOUR_ATATUS_INGESTION_KEY"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="otlp"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"

node app.js

The exporters add /v1/traces, /v1/metrics and /v1/logs to the endpoint themselves. For an ESM app, use NODE_OPTIONS="--experimental-loader=@opentelemetry/instrumentation/hook.mjs --import @opentelemetry/auto-instrumentations-node/register".

Option 2: configure NodeSDK in code

Use this when you want to choose instrumentations, add span processors or set the service name in code. This file uses only SDK 3.x APIs:

// telemetry.js — start with: node --require ./telemetry.js app.js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');
const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-proto');
const { OTLPLogExporter } = require('@opentelemetry/exporter-logs-otlp-proto');
const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
const { BatchLogRecordProcessor } = require('@opentelemetry/sdk-logs');

// The exporters read the endpoint and api-key header from OTEL_EXPORTER_OTLP_* variables
const sdk = new NodeSDK({
  serviceName: 'checkout-api',
  traceExporter: new OTLPTraceExporter(),
  metricReaders: [new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter() })],
  logRecordProcessors: [new BatchLogRecordProcessor({ exporter: new OTLPLogExporter() })],
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

// Flush buffered spans, metrics and logs before the process exits
process.on('SIGTERM', () => {
  sdk.shutdown().finally(() => process.exit(0));
});
npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-proto @opentelemetry/exporter-metrics-otlp-proto \
  @opentelemetry/exporter-logs-otlp-proto @opentelemetry/sdk-metrics @opentelemetry/sdk-logs

export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-rx.atatus.com:443"
export OTEL_EXPORTER_OTLP_HEADERS="api-key=YOUR_ATATUS_INGESTION_KEY"
node --require ./telemetry.js app.js

Keep the API key in the environment variable rather than in the exporter options, so it stays out of your source code.

Option 3: through the OpenTelemetry Collector

If you already run a Collector, point the SDK at it (OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318", no API key needed) and add Atatus as an exporter in the Collector's configuration:

receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:

exporters:
  otlphttp/atatus:
    endpoint: 'https://otel-rx.atatus.com'
    headers:
      api-key: ${env:ATATUS_INGESTION_KEY}

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/atatus]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/atatus]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/atatus]

The Collector decouples your services from the backend: the SDK upgrade and any change of destination happen in different places. The Atatus Collector guide has the full configuration, and the Express setup guide covers the SDK side.

Once data arrives, each service appears in Atatus under its service.name. Open a trace to see every span in the request, how much of the time each service took, and the database and HTTP calls inside it. If you're new to traces, spans and context propagation, start with our beginner's guide to OpenTelemetry.

Frequently asked questions

Is OpenTelemetry JS SDK 3.0 ready for production?

Yes. The stable 3.0.0 packages, the experimental 0.300.0 packages and API 1.10.0 were released on 20 October 2026, and the latest stable release is 3.1.1. Stable 3.x packages follow semantic versioning. Packages still at 0.x, including sdk-node, instrumentation and the OTLP exporters, can still change in minor releases, so pin them to a minor version.

Does OpenTelemetry JS SDK 3.0 support Node.js 20?

No. SDK 3.x needs Node.js 22.15.0 or later. Node.js 18 and 20 are both end-of-life. Only @opentelemetry/api and @opentelemetry/semantic-conventions keep their wider support. A service that has to stay on Node.js 20 can keep using SDK 2.x, which is supported for one year from the 3.0.0 release.

Do I need to change code if I only use auto-instrumentations-node?

Usually not. If you start the SDK with @opentelemetry/auto-instrumentations-node/register and configure it with environment variables, upgrade to Node.js 22.15 or later and to auto-instrumentations-node 0.82.0 or later. Check that OTEL_PROPAGATORS doesn't list jaeger, which is now skipped.

What replaces the Jaeger exporter in OpenTelemetry JS 3.0?

The OTLP trace exporters: @opentelemetry/exporter-trace-otlp-proto, -http or -grpc. Jaeger accepts OTLP natively, so you can keep Jaeger as the backend and point the OTLP exporter at its OTLP port. For context propagation, replace the Jaeger propagator with W3CTraceContextPropagator in every service at the same time.

Where did NodeTracerProvider go?

It's now TracerProvider in @opentelemetry/sdk-trace, which replaces sdk-trace-base, sdk-trace-node and sdk-trace-web. The register() method is gone. Call trace.setGlobalTracerProvider(), context.setGlobalContextManager() and propagation.setGlobalPropagator() from @opentelemetry/api instead.

Can I use @opentelemetry/api 1.10 with SDK 2.x?

No. SDK 2.x packages declare a peer dependency on @opentelemetry/api below 1.10.0. A project on SDK 2.x stays on API 1.9.x, and moving to API 1.10 means moving every SDK package to 3.x at the same time.

Atatus accepts OTLP traces, metrics and logs from SDK 3.x as they are. See OpenTelemetry support in Atatus for how traces, metrics and logs from your Node.js services show up together.

← All posts

Get started

See the root cause first.

Start free and send your first trace with OpenTelemetry or the Atatus agents. APM, logs, RUM, infrastructure and SIEM, all on one timeline.

  • SaaS
  • On-premises
  • Hybrid
  • BYOC
  • No per-user pricing
Keep reading