Loading

Configure EDOT Browser

This page explains how to configure EDOT Browser, which settings are supported, and what's required to start exporting browser telemetry.

EDOT Browser follows OpenTelemetry configuration conventions where possible. Like the upstream OpenTelemetry Browser SDK, it uses explicit configuration at initialization rather than environment variables, which are not available in the browser.

EDOT Browser runs in your users' browsers. Configuration passed to EDOT Browser is accessible to end users, since browser source code and runtime values are visible. This is why you shouldn't embed secrets such as API keys in browser configuration.

Environment variables exist at build time only: a bundler replaces process.env.* with values when bundling, but these values are not available at runtime in the browser. You can provide configuration at build time (bundler-defined constants) or at runtime (options passed to the initialization function).

EDOT Browser does not read OTEL_* variables directly. Instead, it accepts configuration values passed explicitly during initialization.

Typical configuration patterns include:

  • Passing configuration from a server-rendered page.
  • Loading configuration from a global object populated at runtime.

The best approach depends on your application architecture and build tooling.

At a minimum, EDOT Browser requires:

  • A service name to identify the frontend application.
  • An export endpoint that points to a reverse proxy.

You can also set a log level, which is recommended during setup.

import { startBrowserSdk } from '@elastic/opentelemetry-browser';

startBrowserSdk({
  serviceName: 'my-web-app',
  otlpEndpoint: 'https://telemetry.example.com',
  logLevel: 'info',
});
  • serviceName identifies the browser application in Elastic Observability.
  • otlpEndpoint points to a reverse proxy, not directly to Elastic Observability.
  • logLevel controls diagnostic output in the browser console.

Configuration is passed as an object to startBrowserSdk. The following options are supported:

Option Type Description
serviceName string Logical name of the frontend service. Defaults to unknown_service:web if not set.
serviceVersion string Version of the application. Optional.
logLevel string Diagnostic log level (error, warn, info, debug, verbose). Defaults to info.
otlpEndpoint string Base URL of the OTLP export endpoint (reverse proxy). Do not include signal paths such as /v1/traces. Defaults to http://localhost:4318.
sampleRate number Trace sampling ratio (0–1). Defaults to 1 (100%).
resourceAttributes Record<string, any> Optional resource attributes to attach to telemetry. For example: { 'deployment.environment.name': 'production' }.
exportHeaders Record<string, string> Headers to send with export requests. Defaults to {}. The reverse proxy typically injects Authorization; do not put API keys here in browser code.
disabled boolean If true, the SDK does not start.
instrumentations Record<string, Object> Per-instrumentation config. Set { enabled: false } for a key to turn off that instrumentation. Refer to instrumentations details for more information.

Configure otlpEndpoint to point to a server that accepts OTLP traffic. Use the base URL of the server only: do not include signal paths such as /v1/traces, /v1/metrics, or /v1/logs. The SDK appends these paths when exporting each signal.

For security reasons Elastic recommends to configure a reverse proxy that forwards OTLP traffic to Elastic Observability. Refer to Proxy and CORS configuration for more details.

Use a service name that identifies your frontend application and doesn't contain special characters, so that data is correctly categorized in Elastic Observability.

For details on reverse proxy and authorization, refer to OpenTelemetry for Real User Monitoring (RUM).

EDOT Browser uses the OpenTelemetry diagnostic logger.

To troubleshoot setup issues, increase the log level when calling startBrowserSdk:

import { startBrowserSdk } from '@elastic/opentelemetry-browser';

startBrowserSdk({
  serviceName: 'my-web-app',
  otlpEndpoint: 'https://telemetry.example.com',
  logLevel: 'debug',
});

Diagnostic logs are written to the browser console. For more information on using debug logging to troubleshoot issues, refer to Enable debug logging for EDOT SDKs and Enable debug logging (Collector).

This section provides additional details about configuration settings that require further explanation or behave differently in EDOT Browser compared to OpenTelemetry JS.

An object whose keys are the scope names of the available instrumentations in EDOT and whose values are the corresponding configuration objects.

The following keys are supported:

Instrumentation Key (scope name) Configuration
Document load @opentelemetry/instrumentation-document-load Reference
Fetch @opentelemetry/instrumentation-fetch Reference
Long task @opentelemetry/instrumentation-long-task Reference
User interaction @opentelemetry/instrumentation-user-interaction Reference
XMLHttpRequest @opentelemetry/instrumentation-xml-http-request Reference
Web exception @opentelemetry/instrumentation-web-exception Reference
Web vitals @opentelemetry/instrumentation-web-vitals Reference