v3.0.0

3.0.0

Summary

• The minimum supported Node.js has been raised to >=22.15.0. This means that support for Node.js 18 and 20 has been dropped.
• The public interface has changed
  • for notes on migrating to 3.x / 0.300.x see the upgrade guide
• Only experimental versions 0.300.0 are compatible with this release

💥 Breaking Changes

• chore(sdk-trace-node)!: remove the @opentelemetry/sdk-trace-node package #7054
  • The sdk-trace-node package has been replaced by the @opentelemetry/sdk-trace package.
    See the 3.x migration guide for full migration instructions.
• chore(shim-opentracing)!: remove the @opentelemetry/shim-opentracing package
  • In the OpenTelemetry Specification v1.58.0 the OpenTracing compatibility requirements were deprecated. The JavaScript OpenTracing shim package will not receive any more releases after the current 2.11.0 release (source code for last release).
• chore(context-async-hooks)!: remove the unused class AsyncHooksContextManager #7078
• feat!: migrate package builds from tsc to tsdown, emitting dual CJS/ESM output from a single dist/ directory and declaring an exports map on every package #6293 @overbalance
  • Importing a package by its name is unaffected in both CommonJS and ESM, as is every subpath listed in its exports map.
  • Deep imports into the build output no longer resolve. An exports map is an allowlist that Node.js and bundlers enforce, so specifiers such as @opentelemetry/core/build/src/... or @opentelemetry/core/build/esm/... now fail with ERR_PACKAGE_PATH_NOT_EXPORTED. Rewriting them to the new file layout does not help — unlisted subpaths are rejected whether or not the file exists.
  • The emitted files moved out of build/src (CJS), build/esm and build/esnext (ESM) into dist/, using .cjs/.mjs extensions with matching .d.cts/.d.mts declarations.
  • <package>/package.json is no longer importable for the same reason. Read a package's version from your own dependency metadata, or use SDK_INFO from @opentelemetry/core for the SDK version.
  • The non-standard esnext entry point has been removed; tools that preferred it fall back to module (ESM) or main (CJS).
  • Packages that ship separate Node.js and browser implementations export them under explicit subpaths, for example @opentelemetry/core/platform. If you depend on something that is only reachable through a deep import, please open an issue so it can be considered for the public API.
• feat(core)!: remove deprecated getTimeOrigin, otperformance, _globalThis, and unrefTimer from @opentelemetry/core #7053
  • getTimeOrigin() — use performance.timeOrigin directly.
  • otperformance — use the global performance object directly.
  • _globalThis — use globalThis directly.
  • unrefTimer(timer) — call timer.unref() directly in your own code.
• feat(sdk-trace)!: remove deprecated TracerProviderOptions.forceFlushTimeoutMillis #7057
  • Pass timeoutMillis to provider.forceFlush({ timeoutMillis }) instead. The default timeout is 30000ms.
• feat(propagator-jaeger)!: remove @opentelemetry/propagator-jaeger package #7077
  • The Jaeger propagator is deprecated by the OpenTelemetry specification in favour of W3CTraceContextPropagator. Use W3CTraceContextPropagator from @opentelemetry/core instead.
  • See the 3.x migration guide for full instructions.
• feat(exporter-jaeger)!: remove @opentelemetry/exporter-jaeger package
  • The Jaeger exporter has been removed. Jaeger has deprecated its custom Thrift collection protocols in favor of standard OpenTelemetry Protocol (OTLP). Use standard OTLP exporters instead.
  • See the 3.x migration guide for full instructions.
• chore!: bump minimum node.js version to >=22.15.0
• chore(sdk-trace-base, sdk-trace-web)!: remove the @opentelemetry/sdk-trace-base and @opentelemetry/sdk-trace-web packages #7117
  • The sdk-trace-base, sdk-trace-web, and sdk-trace-node packages have been replaced by the @opentelemetry/sdk-trace package.
    See the 3.x migration guide for full migration instructions.
• feat!: replace the browser field in package.json with #platform subpath imports #7141 @overbalance
  • Resolvers with the node condition load the Node.js build; all others load the browser build. Bundlers without imports support fail; see the migration guide.
  • webpack needs 5.54 or later. Parcel needs package exports enabled and cannot resolve #platform from require().
  • Root type declarations describe the Node.js build.
• feat(resources)!: remove the ./detectors/platform and ./detectors/platform/browser subpath exports; import from the package root #7141 @overbalance
• feat(core, sdk-trace, sdk-logs, exporter-zipkin)!: remove the ./platform and ./platform/browser subpath exports; import from the package root #7141 @overbalance
• fix(sdk-logs)!: replace LoggerConfig.disabled with enabled to match the specification #7160
  • Replace disabled: true with enabled: false, and disabled: false with enabled: true. Loggers remain enabled by default.

🚀 Features

• feat(sdk-metrics): stabilize maxExportBatchSize option in PeriodicExportingMetricReader
• chore(sdk-logs): mark @opentelemetry/sdk-logs as stable #7143 @trentm
• feat(sdk-trace, sdk-logs): add the browser-only disableAutoFlushOnDocumentHide to BatchSpanProcessorOptions and BatchLogRecordProcessorOptions, deprecate BatchSpanProcessorBrowserOptions and BatchLogRecordProcessorBrowserOptions #7140 @overbalance

🐛 Bug Fixes

• fix(sdk-metrics): guard against a missing or empty name to MeterProvider#getMeter #7105 @trentm
• fix: resolve the ESM build through the default export condition instead of import, so a resolver that activates neither import nor require still finds an entry point #7132 @overbalance
• fix(sdk-trace): make the Node.js RandomIdGenerator id generators prototype methods, so subclasses can override them #7190 @overbalance
• fix(sdk-logs): report a rejected document-hide flush to the global error handler #7187 @overbalance
• fix(sdk-trace): count attributes passed to startSpan toward attributeCountLimit #7176 @overbalance
• fix(resources): stop reading globalThis.process in the browser build #7173 @overbalance
• fix(core): return false instead of undefined from the browser getBooleanFromEnv #7188 @overbalance
• fix(core): no longer drop an attribute value that is an object that has undefined properties #7207 @trentm
  • isAnyValue() now returns true for {aStr: 'bob', anUndefined: undefined}. This restores the behavior of the old isLogAttributeValue from version 2.x of the sdk-logs package.
  • "Cleaning" of attributes, by cleanAttributes() and maybeAddAttribute(), will now drop undefined properties from objects. For example, logger.emit(attributes: {myAttr: {aStr: 'bob', anUndefined: undefined}, ...) will include attributes: {myAttr: {aStr: 'bob'}}.

📚 Documentation

• chore(examples): drop examples/{otlp-exporter-node,grpc-js} #7096

🏠 Internal

• chore: remove @opentelemetry/sdk-trace-web package from examples and bundler tests #7095
• chore(sdk-trace): add StackContextManager in @opentelemetry/sdk-trace package #7086
• feat(ci): support releasing from maintenance branches #6767 @pichlermarc
  • The API documentation site is only redeployed for releases whose commit is reachable from main, so a maintenance release no longer overwrites it.
• chore: don't close stale issues #x @maryliag
• chore: mark the workspace root package as private #7097 @overbalance
• chore: declare the Node.js and npm version floors that the tsdown build requires via devEngines #7093 @overbalance
  • The migration to tsdown raised the toolchain a contributor needs to build this repo, but nothing declared it. Contributors now build on Node.js ^24.11.1 || >=26.0.0 with npm >=11.10.0; both are advisory and warn rather than fail. The published packages are unaffected and still support Node.js >=22.15.0, which the test matrix continues to cover.
• test(bundler-tests): typecheck packages under legacy module resolution #7127 @overbalance
• chore: remove the redundant module field from package.json; bundlers resolve the ESM build through the exports map #7130 @overbalance
• test(bundler-tests): bundle the platform packages for iOS and Android with Metro and Expo, and load them under Jest's jsdom environment #7131 @overbalance
• fix(verify-pack): read the npm 12 pack --json output, which is keyed by package name instead of an array #7133 @overbalance
• fix(karma): resolve plugins and the process shim from the repo root, so browser tests run with isolated installs #7137 @overbalance
• fix(nx): key the version target defaults by the target name, so a cache hit restores the generated src/version.ts #7134 @overbalance
• fix(nx): make the test, test:browser and test:webworker targets compile their dependencies first, since tests load dependencies from their dist #7139 @overbalance
• fix(verify-pack): extract tarballs under the root node_modules, so workspace dependencies resolve and entry points load fully instead of being skipped #7138 @overbalance
• build: lint published packages for unused dependencies with knip, as part of npm run lint #7200 @overbalance
• chore(exporter-zipkin): move @opentelemetry/resources to devDependencies, since only tests use it #7200 @overbalance
• build: fail the tsdown build when its output includes a module from outside the package #7195 @overbalance
• refactor(sdk-trace): remove the pagehide listener from the browser BatchSpanProcessor, it was registered on document and never ran, and visibilitychange already flushes on unload #7153 @adityareddy-dev
• refactor(sdk-logs): remove the pagehide listener from the browser BatchLogRecordProcessor, it was registered on document and never ran, and visibilitychange already flushes on unload #7153 @adityareddy-dev
• refactor(sdk-trace, sdk-logs, sdk-metrics): type timers with ReturnType<typeof setTimeout> instead of NodeJS.Timeout #7174 @overbalance