Migrate or deprecate browser packages from opentelemetry-js and opentelemetry-js-contrib

[martinkuba]

Browser-specific packages are currently spread across three repositories: opentelemetry-js, opentelemetry-js-contrib, and this repository (opentelemetry-browser). This makes it harder to maintain a coherent browser observability story and creates confusion for users about where to find browser-specific packages.

The goal of this effort is to consolidate all browser-specific packages into this repository, deprecating the original packages and providing clear migration paths. This includes both instrumentations and supporting infrastructure (SDK components, context managers, resource detectors, and shared utilities).

Instrumentations

Event-based instrumentations (straightforward move)

These are newer, event-based instrumentations that can be added directly to the @opentelemetry/browser-instrumentation package as subpath exports.

• instrumentation-browser-navigation from contrib
• instrumentation-web-exception from contrib

Span-based instrumentations (important, needs migration planning)

These are widely used, span-based instrumentations that require careful migration planning to minimize disruption for existing users.

• instrumentation-fetch from opentelemetry-js
• instrumentation-xml-http-request from opentelemetry-js

Span-based instrumentations (needs discussion)

These are more experimental, span-based instrumentations. Each one needs individual discussion about whether to move, deprecate, or replace with a new implementation.

• instrumentation-document-load — overlaps with navigation-timing
• instrumentation-long-task — Long Task API being superseded by Long Animation Frames API
• instrumentation-user-interaction — overlaps with user-action, zone.js dependency concerns
• plugin-react-load — unmaintained, outdated

Non-instrumentation browser packages (needs discussion)

These are SDK components in opentelemetry-js that are browser-specific. They need discussion on whether and how to migrate them, as they have implications for the broader SDK architecture.

• sdk-trace-web — WebTracerProvider and web-specific trace utilities (stable, v2.6.0)
• web-common — session management utilities (experimental)
• browser-detector — browser resource detector (experimental)
• context-zone / context-zone-peer-dep — Zone.js context managers (stable, v2.6.0)

Metapackage

• auto-instrumentations-web — metapackage bundling browser instrumentations

[martinkuba]

I can create sub-issues for each of these if needed.

[david-luna]

@martinkuba

regarding fetch and XHR instrumentations I remember a discussion in the scope of open-telemetry/opentelemetry-js-contrib#2928 about moving all instrumentations to contrib (http, fetch and XHR). If I recall correctly the argument to not do it was about keeping platform/runtime APIs instrumentations in core and other instrumentations in contrib.

Since most or all instrumentations need to patch browser APIs I think this reasoning does not apply. I'll bring this topic again in the JS SIG and update this comment with the feedback.