Elastic Distribution of OpenTelemetry Browser breaking 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.

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.