OpenTelemetry Browser

About

This repository is the home of OpenTelemetry Browser instrumentations and the future home of the OpenTelemetry Browser SDK.

This repo provides event-based instrumentations that emit events (structured log records) for browser performance and user interactions. These complement the existing span-based instrumentations maintained in the opentelemetry-js and opentelemetry-js-contrib repositories.

See the Browser Packages section below for a full list of browser-related packages across all repositories.

Quick Start

Installation

npm install @opentelemetry/browser-instrumentation \
  @opentelemetry/api \
  @opentelemetry/api-logs \
  @opentelemetry/sdk-logs \
  @opentelemetry/instrumentation

Basic example

import { logs } from '@opentelemetry/api-logs';
import {
  ConsoleLogRecordExporter,
  LoggerProvider,
  SimpleLogRecordProcessor,
} from '@opentelemetry/sdk-logs';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { NavigationTimingInstrumentation } from '@opentelemetry/browser-instrumentation/experimental/navigation-timing';
import { ResourceTimingInstrumentation } from '@opentelemetry/browser-instrumentation/experimental/resource-timing';
import { UserActionInstrumentation } from '@opentelemetry/browser-instrumentation/experimental/user-action';
import { WebVitalsInstrumentation } from '@opentelemetry/browser-instrumentation/experimental/web-vitals';
import { ConsoleInstrumentation } from '@opentelemetry/browser-instrumentation/experimental/console';

const logProvider = new LoggerProvider({
  processors: [
    new SimpleLogRecordProcessor(new ConsoleLogRecordExporter()),
  ],
});
logs.setGlobalLoggerProvider(logProvider);

registerInstrumentations({
  instrumentations: [
    new NavigationTimingInstrumentation(),
    new ResourceTimingInstrumentation(),
    new UserActionInstrumentation(),
    new WebVitalsInstrumentation(),
    new ConsoleInstrumentation(),
  ],
});

For detailed configuration options, see the instrumentation package README.

More examples

For a more complete setup combining event-based instrumentations from this repository with span-based instrumentations from opentelemetry-js and opentelemetry-js-contrib, see the examples directory.

Sandbox

Interactive playground for testing OpenTelemetry browser instrumentations. Configure the SDK, trigger actions (fetch, XHR, errors, navigation…), and inspect exported spans and logs in real time.

Run locally

npm install
npm run dev

This starts the sandbox with hot-reload via Vite at http://localhost:5173.

GitHub Pages

The sandbox is automatically deployed to GitHub Pages on every push to main via the deploy-sandbox.yml workflow. The live site is available at open-telemetry.github.io/opentelemetry-browser.

Browser Packages

The following tables list browser-related packages across all OpenTelemetry JS repositories.

Packages in this repository

Package	Description	Status
@opentelemetry/browser-instrumentation	Event-based browser instrumentations (navigation timing, resource timing, user actions, web vitals, console).	experimental

Event-based instrumentations (other repositories)

Package	Location	Description	Status
instrumentation-browser-navigation	opentelemetry-js-contrib	Capture browser navigation events (SPA route changes).	experimental
instrumentation-web-exception	opentelemetry-js-contrib	Capture unhandled exceptions and promise rejections.	experimental

Span-based instrumentations (other repositories)

Package	Location	Description	Status
opentelemetry-instrumentation-fetch	opentelemetry-js	Instrumentation for the Fetch API.	experimental
opentelemetry-instrumentation-xml-http-request	opentelemetry-js	Instrumentation for XMLHttpRequest.	experimental
instrumentation-document-load	opentelemetry-js-contrib	Capture document load/navigation timing spans.	experimental
instrumentation-long-task	opentelemetry-js-contrib	Capture Long Tasks API entries as spans.	experimental
instrumentation-user-interaction	opentelemetry-js-contrib	Trace user interactions (e.g., clicks).	experimental
plugin-react-load	opentelemetry-js-contrib	Instrument React application load/mount performance.	experimental

SDK and Utilities (other repositories)

Package	Location	Description	Status
opentelemetry-sdk-trace-web	opentelemetry-js	Browser tracing SDK (WebTracerProvider, web tracing setup).	stable
opentelemetry-browser-detector	opentelemetry-js	Resource detector for browser environment attributes.	experimental
web-common	opentelemetry-js	Shared utilities for browser/web instrumentations.	experimental
opentelemetry-context-zone	opentelemetry-js	Zone.js-based context manager for maintaining trace context in browsers.	stable
auto-instrumentations-web	opentelemetry-js-contrib	Bundle that auto-enables common web instrumentations.	experimental

Contributing

Prerequisites

Contributing to this project requires Node.js >= 24 and npm ^11.9.0

npm install -g npm@11

Maintainers

• David Luna, Elastic
• Jared Freeze, Embrace
• Joaquín Díaz, Embrace
• Martin Kuba, Grafana Labs
• Wolfgang Therrien, Honeycomb

For more information about the maintainer role, see the community repository.

Approvers

• Maxime Quentin, Datadog

For more information about the approver role, see the community repository.

Emeritus

• Benoît Zugmeyer, Approver
• Ted Young, Maintainer

For more information about the emeritus role, see the community repository.