otel-browser

OpenTelemetry in the Browser (RUM)

Entry point for OpenTelemetry mechanics in web apps. Load a reference below based on the task; each reference is self-contained.

Stability: Browser/RUM is one of the newest and most experimental areas of OpenTelemetry. Only the web tracing primitives (@opentelemetry/sdk-trace-web, @opentelemetry/context-zone) and the JS API are stable today. The Browser SDK (@opentelemetry/browser-sdk) and the event-based instrumentations are experimental and may break between minor versions — pin exact versions. Verify current status via the Sources of Truth below.

References

File	Use when
references/setup-sdk.md	Wiring up the SDK: the direct providers (WebTracerProvider + ZoneContextManager for spans; LoggerProvider for events) vs the experimental browser-sdk, sessions, frontend→backend traceparent/CORS propagation, and why a Collector sits in front.
references/instrumentation.md	Choosing and configuring instrumentations: the event-based catalog (navigation, web vitals, console, errors, …), the span-based catalog (fetch, XHR, document-load, long-task, …), per-instrumentation options, and what each captures.
references/performance.md	Keeping it cheap, fast, and private: bundle size, off-main-thread processing, page-lifecycle flushing, telemetry volume/cost, and PII vectors.

Two telemetry models — read first

Browser telemetry is modeled as spans and events; there is no browser metrics story yet (metrics are out of scope for the Browser SDK). Picking the right model per signal is the first decision:

Model	Signal	For	Examples
Events	Logs API → LogRecord	point-in-time facts (no duration/children)	web vitals, navigation, console, errors, user action
Spans	Trace API	operations with a duration and parent/child	fetch, XHR, document load, long task

Verify attributes against released semantic conventions before hand-rolling

Not every browser signal has a released convention yet — e.g. browser.web_vital is a released development-stability event, but browser.navigation and browser.resource_timing have no released convention under the browser group, and exception is a released stable group of its own (not under browser). Check coverage per signal rather than assuming it; before emitting a hand-written span or LogRecord with custom attributes:

1. Prefer a catalog instrumentation from references/instrumentation.md — it already emits compliant event/attribute names where a convention exists.
2. Check whether a released convention covers the signal: use the otel-semantic-conventions skill to query the relevant group (e.g. browser for event.browser.web_vital, exceptions for exception.type), or WebFetch the matching page under https://opentelemetry.io/docs/specs/semconv/browser/.
3. If one exists, use its event/attribute names verbatim (e.g. the browser.web_vital event's name, value, delta, id — not a custom web_vital.* namespace), even at development stability. If none exists, define bounded, low-cardinality custom attributes under a stable namespace instead of guessing at a released-looking name.

The browser package ecosystem — three repositories

Browser packages are spread across three upstream repos. The opentelemetry-browser README "Browser Packages" tables are the authoritative, current map. Summary:

Package	Repo	Model	Stability
@opentelemetry/sdk-trace-web	opentelemetry-js	SDK (spans)	stable
@opentelemetry/context-zone	opentelemetry-js	context	stable
@opentelemetry/instrumentation-fetch	opentelemetry-js	spans	experimental
@opentelemetry/instrumentation-xml-http-request	opentelemetry-js	spans	experimental
@opentelemetry/browser-detector	opentelemetry-js	resource	experimental
@opentelemetry/browser-instrumentation	opentelemetry-browser	events	experimental
@opentelemetry/browser-sdk	opentelemetry-browser	SDK	experimental (0.x)
@opentelemetry/auto-instrumentations-web	opentelemetry-js-contrib	bundle	experimental
instrumentation-document-load / -long-task / -user-interaction	opentelemetry-js-contrib	spans	experimental
instrumentation-browser-navigation / -web-exception	opentelemetry-js-contrib	events	experimental
plugin-react-load	opentelemetry-js-contrib	spans	unmaintained

opentelemetry-browser is the home of the event-based instrumentations and the experimental Browser SDK; the span-based packages still live in opentelemetry-js / opentelemetry-js-contrib.

Why browser RUM is different

These constraints drive most design decisions (detailed in the references):

• The process disappears — no graceful shutdown. Flush on visibilitychange/pagehide; browser exporters use keepalive when limits allow it. Do not rely on unload.
• No gRPC — export is OTLP/HTTP only (protobuf or JSON).
• Cross-origin propagation is opt-in — traceparent is not sent to other origins unless you set propagateTraceHeaderCorsUrls and the server allows the header via Access-Control-Allow-Headers.
• The client is untrusted and chatty — put a Collector (or vendor edge) between browsers and your backend for CORS termination, sampling, redaction, and rate limiting.
• PII is everywhere — URLs, console output, form fields, and click targets routinely carry it.

Sources of Truth

Browser packages move fast while experimental — fetch current versions and status rather than relying on these notes.

Fact	Fetch
opentelemetry-browser package versions / status	gh api repos/open-telemetry/opentelemetry-browser/releases -q '.[].tag_name'
Latest @opentelemetry/browser-instrumentation	npm view @opentelemetry/browser-instrumentation version
Latest @opentelemetry/browser-sdk (0.x, published)	npm view @opentelemetry/browser-sdk version
Latest @opentelemetry/sdk-trace-web	npm view @opentelemetry/sdk-trace-web version
Latest @opentelemetry/auto-instrumentations-web	npm view @opentelemetry/auto-instrumentations-web version
Authoritative browser package map	WebFetch https://github.com/open-telemetry/opentelemetry-browser#browser-packages
browser-instrumentation README / config	WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-browser/main/packages/instrumentation/README.md
browser.* event semantic-convention status	WebFetch https://opentelemetry.io/docs/specs/semconv/browser/

Cross-References

• Shared JS API and Node.js SDK (the browser builds on the same API): otel-js skill.
• Schema-level facts for declarative YAML config: otel-declarative-config skill.
• Semantic conventions lookup (browser.*, session.*, exception): otel-semantic-conventions skill — use it before hand-rolling any event/span attributes (see above).
• Edge sampling / redaction / rate limiting in front of browsers: otel-collector skill.
• SDK version selection across languages: otel-sdk-versions skill.