@opentelemetry/sdk-metrics

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

:boom: Breaking Changes

• breaking

  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.

• breaking

  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).

• breaking

  context-async-hooks: remove the unused class AsyncHooksContextManager #7078

• breaking

  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

  • 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.

• breaking

  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.

• breaking

  sdk-trace: remove deprecated TracerProviderOptions.forceFlushTimeoutMillis #7057

  • Pass timeoutMillis to provider.forceFlush({ timeoutMillis }) instead. The default timeout is 30000ms.

• breaking

  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.

• breaking

  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.

• breaking

  bump minimum node.js version to >=22.15.0

• breaking

  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.

• breaking

  replace the browser field in package.json with #platform subpath imports #7141

  • 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.

• breaking

  resources: remove the ./detectors/platform and ./detectors/platform/browser subpath exports; import from the package root #7141

• breaking

  core, sdk-trace, sdk-logs, exporter-zipkin: remove the ./platform and ./platform/browser subpath exports; import from the package root #7141

• breaking

  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.

:rocket: Features

• sdk-metrics: stabilize maxExportBatchSize option in PeriodicExportingMetricReader

• sdk-trace, sdk-logs: add the browser-only disableAutoFlushOnDocumentHide to BatchSpanProcessorOptions and BatchLogRecordProcessorOptions, deprecate BatchSpanProcessorBrowserOptions and BatchLogRecordProcessorBrowserOptions #7140

:bug: Bug Fixes

• sdk-metrics: guard against a missing or empty name to MeterProvider#getMeter #7105

• 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

• sdk-trace: make the Node.js RandomIdGenerator id generators prototype methods, so subclasses can override them #7190

• sdk-logs: report a rejected document-hide flush to the global error handler #7187

• sdk-trace: count attributes passed to startSpan toward attributeCountLimit #7176

• resources: stop reading globalThis.process in the browser build #7173

• core: return false instead of undefined from the browser getBooleanFromEnv #7188

• core: no longer drop an attribute value that is an object that has undefined properties #7207

  • 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'}}.

:house: Internal

• ci: support releasing from maintenance branches #6767

  • The API documentation site is only redeployed for releases whose commit is reachable from main, so a maintenance release no longer overwrites it.

• verify-pack: read the npm 12 pack --json output, which is keyed by package name instead of an array #7133

• karma: resolve plugins and the process shim from the repo root, so browser tests run with isolated installs #7137

• nx: key the version target defaults by the target name, so a cache hit restores the generated src/version.ts #7134

• nx: make the test, test:browser and test:webworker targets compile their dependencies first, since tests load dependencies from their dist #7139

• verify-pack: extract tarballs under the root node_modules, so workspace dependencies resolve and entry points load fully instead of being skipped #7138

:house: Internal

• ci: support releasing from maintenance branches #6767

  • The API documentation site is only redeployed for releases whose commit is reachable from main, so a maintenance release no longer overwrites it.

:rocket: Features

• context-async-hooks: implement attach() on AsyncLocalStorageContextManager #6845

  • On Node.js 25.9+, delegates to AsyncLocalStorage.withScope() returning a native RunScope. On older Node.js, falls back to enterWith() with a manual disposable wrapper.

• sdk-trace: allow configuring the force flush timeout per call #6929 @LarryHu0217

:bug: Bug Fixes

• sdk-metrics: ignore Infinity in exponential histograms #7015

:house: Internal

• sdk-metrics: reuse a single DataView for exponential histogram bit reads #6998

• ci: support pre-releases and major version bumps in the release workflow #6768