@opentelemetry/web-common

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 stable versions 3.0.0 are compatible with this release

:boom: Breaking Changes

• breaking

  shim-opencensus: remove the @opentelemetry/shim-opencensus package

  • In the OpenTelemetry Specification v1.58.0 the OpenCensus compatibility requirements were deprecated. The JavaScript OpenCensus shim package will not receive any more releases after the current 0.222.0 release (source code for last release).

• breaking

  instrumentation-http: remove deprecated serverName field from HttpInstrumentationConfig #7081

  • The serverName option had no effect; stable HTTP semantic conventions do not include http.server_name. Remove it from any setConfig() or constructor call.

• breaking

  sdk-node: remove deprecated NodeSDKConfiguration fields logRecordProcessor, metricReader, spanProcessor and deprecated namespace re-exports node, tracing

  • NodeSDKConfiguration.logRecordProcessor — use logRecordProcessors instead.

  • NodeSDKConfiguration.metricReader — use metricReaders instead.

  • NodeSDKConfiguration.spanProcessor — use spanProcessors instead.

  • export * as node from '@opentelemetry/sdk-node' — import directly from @opentelemetry/sdk-trace-node instead.

  • export * as tracing from '@opentelemetry/sdk-node' — import directly from @opentelemetry/sdk-trace-base instead.

• breaking

  sdk-logs: remove deprecated SdkLogRecord type alias and LoggerProviderConfig type alias #7062

  • SdkLogRecord — use ReadWriteLogRecord instead.

  • LoggerProviderConfig — use LoggerProviderOptions instead.

• 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/sdk-logs/build/src/... or @opentelemetry/sdk-logs/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/sdk-logs/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

  sdk-node: remove "jaeger" propagator from @opentelemetry/sdk-node #7077

  • OTEL_PROPAGATORS=jaeger and { jaeger: null } in the configuration object are no longer recognised. Replace with "tracecontext".

  • See the 3.x migration guide for full instructions.

• breaking

  opentelemetry-exporter-prometheus: default exporter host to localhost #6599

• breaking

  bump minimum node.js version to >=22.15.0

• breaking

  api-logs: move the Logs API to @opentelemetry/api and remove the standalone @opentelemetry/api-logs package #4862

• breaking

  exporter-prometheus: stop reading Prometheus exporter host and port environment variables in the exporter constructor #6966

• breaking

  web-common: clean up and deprecate network span utils #7114

  • These utilities were long planned for removal. They were moved from the sdk-trace-web package and are currently only used by the (deprecated) instrumentation-fetch and instrumentation-xml-http-request packages.

  • Drop the skipOldSemconvContentLengthAttrs vestigial option from addSpanNetworkEvents().

• breaking

  sdk-node: drop SDK package re-exports (api, contextBase, core, logs, metrics, resources) #7111

  • api / contextBase → import from @opentelemetry/api

  • core → import from @opentelemetry/core

  • logs → import from @opentelemetry/sdk-logs

  • metrics → import from @opentelemetry/sdk-metrics

  • resources → import from @opentelemetry/resources

• breaking

  sdk-logs: mark @opentelemetry/sdk-logs as stable #7143

  • See the stable CHANGELOG for future changes to the sdk-logs package.

• 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

  instrumentation, exporter--otlp-http, exporter--otlp-proto: remove the ./platform and ./platform/browser subpath exports; import from the package root #7141

• breaking

  otlp-exporter-base: move OTLPExporterNodeConfigBase to @opentelemetry/otlp-exporter-base/node-http #7172

  • typesVersions maps the subpaths for moduleResolution: node.

:rocket: Features

• refactor!(api-logs): remove AnyValue-related types in favor of new types in the api package #6780

  • The AnyValue, LogBody, and LogAttributes types are no longer exported by the api-logs package.
    Instead, use the AnyValue and Attributes types from the latest @opentelemetry/api package.

  • This is part of supporting OTEP 4485.

• instrumentation: add isEnabled() to the browser InstrumentationBase; fetch and XHR report false when patching throws #7140

• breaking

  instrumentation: make InstrumentationBase#_enabled protected on both platforms #7202

  • The browser base no longer tracks enable() and disable() calls. Browser subclasses set _enabled themselves; one that never sets it reports isEnabled() as false.

  • A browser subclass that declares its own private _enabled fails to compile; rename it or declare it protected.

:bug: Bug Fixes

• otlp-exporter-base: suppress tracing around the browser fetch transport's own request so a fetch instrumentation cannot create an export → span → export loop #6948

• instrumentation-http: set error.type on spans whose status code makes them an error #7061

• exporter-prometheus: prevent duplicate metric metadata and keep metric families grouped across instrumentation scopes in Prometheus scrapes #7047

• configuration: preserve zero-valued limits from environment variables #7060

• otlp-exporter-base: release the keepalive budget once the response body drains, instead of holding up the export until it does #7070

• web-common: export getElementXPath utility

  • This was accidentally missed when moving utilities from sdk-trace-web to web-common.

• opentelemetry-browser-detector: mark the package side-effect free so bundlers can tree-shake it #7135

• 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

• instrumentation-fetch: define PropagateTraceHeaderCorsUrls locally, so the types no longer import @opentelemetry/web-common #7193

• web-common: declare @opentelemetry/sdk-trace and @opentelemetry/sdk-logs as dependencies #7193

• instrumentation-fetch, instrumentation-xml-http-request: stay disabled when fetch or XMLHttpRequest open/send is missing, so a later enable() retries #7171

• instrumentation: move InstrumentationNodeModuleFile behind #platform, so the root types no longer import Node.js path #7177

• otlp-transformer: accept DOM TextDecoder in ProtobufReader typing #7169

:boom: Breaking Changes

• breaking

  web-common: clean up and deprecate network span utils #7114

  • These utilities were long planned for removal. They were moved from the sdk-trace-web package and are currently only used by the (deprecated) instrumentation-fetch and instrumentation-xml-http-request packages.

  • Drop the skipOldSemconvContentLengthAttrs vestigial option from addSpanNetworkEvents().

:boom: Breaking Changes

• breaking

  sdk-node: fail-fast on Propagator creation from config file #6930

• breaking

  sdk-node: fail-fast on MeterProvider creation from config file #6954

• breaking

  sdk-node: fail-fast on TracerProvider creation from config file #6962

• breaking

  sdk-node: fail-fast on Resource creation from config file #6989

  • This also breaks some usage of startNodeSDK() for environment-based config, i.e. when not using a config file. For example with OTEL_NODE_RESOURCE_DETECTORS=all, it results in an error message and a no-op SDK.
    (This does not impact users of new NodeSDK() -- the currently recommended mechanism to start an SDK using this package.)

    Could not create OpenTelemetry SDK from configuration, SDK will not be setup: unknown ExperimentalResourceDetector name in configuration: "container"

:rocket: Features

• deprecated

  sdk-logs: deprecate SdkLogRecord in favor of ReadWriteLogRecord #6939

:bug: Bug Fixes

• instrumentation-http: redact sensitive query parameters on incoming (server) spans; add redactedQueryParamsServer config option @dyladan

• sdk-node: support headers_list when creating OTLP exporters from declarative configuration #6953