
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
- Who has to change code
- Breaking changes checklist
- Migrating from 2.x, step by step
- What stable logs means for Node.js
- Sending OpenTelemetry traces, metrics and logs to Atatus
- Frequently asked questions
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.
| Change | What it means for a Node.js service |
|---|---|
Node.js >=22.15.0 | Node.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 exports | Imports 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 package | sdk-trace-base, sdk-trace-node and sdk-trace-web are replaced by @opentelemetry/sdk-trace. NodeTracerProvider becomes TracerProvider, and register() is gone. |
| Logs are stable | The Logs API moved into @opentelemetry/api, and @opentelemetry/api-logs was removed. @opentelemetry/sdk-logs is now a stable 3.x package. |
| Deprecated packages removed | The Jaeger exporter and propagator and the OpenTracing and OpenCensus shims are gone. |
| Complex attribute values | Span 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/registerthroughNODE_OPTIONSand configure everything withOTEL_*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 isOTEL_PROPAGATORS:jaegeris no longer recognized, so it's skipped with a warning. - NodeSDK in a setup file. If you create
NodeSDKin your owntelemetry.js, expect a few small changes. The singularspanProcessor,metricReaderandlogRecordProcessoroptions are gone, the namespace re-exports such astracingandresourcesare gone, and imports fromsdk-trace-basemove tosdk-trace. - A tracer provider built by hand. If you create
NodeTracerProviderorBasicTracerProvideryourself, you have the most to change: the class name, the span processor constructors, theregister()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
importsandexportsfields inpackage.jsonand resolve thenodecondition. 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 withERR_PACKAGE_PATH_NOT_EXPORTED. Import from the package name.<package>/package.jsoncan't be imported either, so read the SDK version fromSDK_INFOin@opentelemetry/core. @opentelemetry/sdk-trace-base,sdk-trace-nodeorsdk-trace-webin your dependencies. Replace them with@opentelemetry/sdk-trace.BasicTracerProvider,NodeTracerProviderandWebTracerProviderall becomeTracerProvider.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 toSimpleSpanProcessor.- Sampler, batch and limit environment variables with a manual provider.
sdk-traceno longer readsOTEL_TRACES_SAMPLER,OTEL_TRACES_SAMPLER_ARG, theOTEL_BSP_*variables or the attribute and span limit variables. Pass these values in code, or useNodeSDK, 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-jaegerorOTEL_PROPAGATORS=jaeger. Removed. UseW3CTraceContextPropagator. Every service that sends or receives trace context has to switch, or traces break at the services that haven't.@opentelemetry/shim-opentracingorshim-opencensus. Removed. Move that instrumentation to the OpenTelemetry API first. The background is in OpenTelemetry vs OpenTracing.@opentelemetry/api-logs. Removed. ImportlogsandSeverityNumberfrom@opentelemetry/api.AsyncHooksContextManager. Removed. UseAsyncLocalStorageContextManagerfrom the same package,@opentelemetry/context-async-hooks.- Singular options on
NodeSDK.spanProcessor,metricReaderandlogRecordProcessorare removed. Use the array optionsspanProcessors,metricReadersandlogRecordProcessors.traceExporterstill works. - Namespace imports from
@opentelemetry/sdk-node.api,contextBase,core,logs,metrics,resources,nodeandtracingare no longer re-exported. Import from the real packages. forceFlushTimeoutMillis. Removed fromTracerProvideroptions. 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.
serverNameonHttpInstrumentation. Removed. It had no effect, so delete it.PrometheusExporterexposed to other hosts. It now binds tolocalhostby default and no longer reads its host and port variables. Passhostandportto 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
nodecondition is applied: esbuildplatform: 'node', a Node.js webpacktarget, ornodein Rollup'sexportConditions.
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-idheaders, run both propagators side by side withCompositePropagatoruntil every service reads and writestraceparent. Do this on 2.x:propagator-jaeger@2needs@opentelemetry/apibelow 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_EXPORTEDat 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.logsandSeverityNumberare imported from the same package astraceandmetrics, with the same stability promise. The separate@opentelemetry/api-logspackage is gone. @opentelemetry/sdk-logsis stable. It jumped from 0.x to 3.x, so itsLoggerProviderand 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-nodeare 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.


