Type to search.

Elastic Distribution of OpenTelemetry Browser breaking changes

Serverless Observability

Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud.

Availability

  • Generally available

    This functionality is generally available and ready for production usage.

Stack

The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats.

Availability

  • Generally available

    This functionality is generally available and ready for production usage.

Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments.

This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

Breaking changes can impact your applications, potentially disrupting normal operations. Before you upgrade, carefully review the Elastic Distribution of OpenTelemetry breaking changes and take the necessary steps to mitigate any issues.

Session sampling replaces root sampleRate

EDOT Browser now applies sampling at session scope. Configure the rate with session.sampleRate (0–1). The former top-level sampleRate option (trace-ID ratio sampling) is removed. Impact

  • Top-level sampleRate is ignored at runtime. TypeScript types may still list it until updated.
  • Sampling is per session, not per trace ID. For a sampled session, automatic spans and log records are collected for the whole session; for an unsampled session, instrumentations are disabled. Action
  • Move sampleRate into session: { sampleRate: … }.
  • Revisit dashboards and volume estimates if you relied on trace-ID sampling for partial span volume within a single user session. Refer to PR #128.
Replacement of document load instrumentation for navigation timing

Document instrumentation (@opentelemetry/instrumentation-document-load) has been replaced by navigation-timing from @opentelemetry/browser-instrumentation. The new instrumentation emits a log records instead of a trace Span to report the timings. Impact

  • TypeScript users see a compilation error if they still use the old instrumentation key or options.
  • At runtime, configuration under the old key is ignored.
  • Document load no longer produce spans.
  • Load timings are exported on the logs signal (/v1/logs), not traces. Action
  • Remove instrumentations['@opentelemetry/instrumentation-document-load'] configutration option.
  • Update dashboards/queries that relied on document-load spans to use navigation-timing log events instead. Refer to PR #102.
Switch to new user action instrumentation

User interaction instrumentation (@opentelemetry/instrumentation-user-interaction) has been replaced by user-action from @opentelemetry/browser-instrumentation. The new instrumentation emits log records (for example browser.user_action.click) instead of trace spans. Impact

  • TypeScript users see a compilation error if they still use the old instrumentation key or options.
  • At runtime, configuration under the old key is ignored.
  • Clicks no longer produce spans. Subsequent fetch / XHR spans are no longer grouped under a click parent span in trace views.
  • User actions are exported on the logs signal (/v1/logs), not traces.
  • submit and other event types previously configured via eventNames are not supported by user-action (only click today). This change produces a compilation error Action
  • Change instrumentations['@opentelemetry/instrumentation-user-interaction'] to instrumentations['user-action'].
  • Replace eventNames with autoCapturedActions (for example ['click']).
  • Replace span hooks (shouldPreventSpanCreation) with applyCustomLogRecordData.
  • Update dashboards/queries that relied on user-interaction spans to use user-action log events instead. Refer to PR #101.
Configuration change for export

The export configuration (url, headers) has been grouped to a new key named exportConfig. This aligns with the configuration type of the upstream SDK. Impact
This change produces a compilation error if you use the SDK with TypeScript. At runtime the old configuration options will be ignored and EDOT will export to the default endpoint http://localhost:4318. Action
Put the otlpEndpoint configuration value into the new key exportConfig.url. Put the exportHeaders configuration value into the new key exportConfig.headers. Refer to PR #100.

Configuration change in fetch instrumentation

The configuration key for fetch instrumentation has changed from @opentelemetry/instrumentation-fetch to a shorter name fetch. Impact
This change produces a compilation error if you use the SDK with TypeScript. At runtime the configuration will be ignored if using the old configuration key. Action
Change the configuration key to fetch. Refer to PR #97.

Configuration change in XmlHttpRequest instrumentation

The configuration key for xml-http-request instrumentation has changed from @opentelemetry/instrumentation-xml-http-request to a shorter name xhr. Impact
This change produces a compilation error if you use the SDK with TypeScript. At runtime the configuration will be ignored if using the old configuration key. Action
Change the configuration key to xhr. Refer to PR #97.

Signature change in XmlHttpRequest applyCustomAttributesOnSpan hook

The applyCustomAttributesOnSpan callback for xhr instrumentation now receives (span, xhr) instead of (span, xhr, result). Impact
Custom attribute hooks that read the third result argument will no longer receive response data. TypeScript users may see compilation errors if their hook signature still expects three arguments. Action
Update xhr instrumentation hooks to use (span, xhr) and read response attributes from the xhr object (for example, xhr.status) instead of the removed third argument. Refer to PR #97.

Removal of ignoreNetworkEvents in fetch and XmlHttpRequest instrumentations

The ignoreNetworkEvents configuration option is no longer supported for fetch and xhr instrumentations. Impact
If you previously set ignoreNetworkEvents: true to suppress network events on HTTP spans, that setting is ignored and network events may appear in exported spans again. Action
Remove ignoreNetworkEvents from your fetch and xhr instrumentation configuration. If you need to exclude specific requests from tracing, use ignoreUrls instead. Refer to PR #97.

Configuration change in navigation instrumentation

The configuration key for navigation instrumentation has changed from @opentelemetry/instrumentation-browser-navigation to a shorter name navigation. Impact
This change produces a compilation error if you use the SDK with TypeScript. At runtime the configuration will be ignored if using the old configuration key. Action
Change the configuration key to navigation. Refer to PR #96.

Configuration change in web exception instrumentation

The configuration key for web-exception instrumentation has changed from @opentelemetry/instrumentation-web-exception to a shorter name errors. Impact
This change produces a compilation error if you use the SDK with TypeScript. At runtime the configuration will be ignored if using the old configuration key. Action
Change the configuration key to errors. Refer to PR #95.

Configuration change in web vitals instrumentation

The configuration key for web-vitals instrumentation has changed from @opentelemetry/instrumentation-web-vitals to a shorter name web-vitals. Impact
This change produces a compilation error if you use the SDK with TypeScript. At runtime the configuration will be ignored if using the old configuration key: web vitals turned off with { enabled: false } are collected again, and hooks such as applyCustomLogRecordData stop running. Action
Change the configuration key to web-vitals. Refer to PR #107.