OpenTelemetry Traces from the Browser

The OpenTelemetry JavaScript SDK for browsers consists of several packages: @opentelemetry/sdk-trace-web provides the core tracing implementation, @opentelemetry/instrumentation-fetch automatically creates spans for all fetch API calls, and @opentelemetry/exporter-trace-otlp-http sends spans to a collector.

The TracerProvider is the central configuration object in OpenTelemetry. It holds the list of SpanProcessors (which determine what happens to completed spans), the resource describing your application (service name, version), and any sampling configuration.

The BatchSpanProcessor collects completed spans in memory and exports them in batches rather than sending each span individually. This dramatically reduces the number of HTTP requests to your collector, improving browser performance and reducing load on the OTel collector endpoint.

OTLPTraceExporter sends batched spans to an OpenTelemetry-compatible collector via HTTP in JSON or protobuf format. You configure the collector URL (e.g., your OTel Collector proxy endpoint), and the exporter handles serialization and retry logic automatically.

A Span represents a single unit of work within a trace: a component mount, an API call, a user interaction. Spans have a name, start time, end time, status (OK or ERROR), and a set of key-value attributes. Related spans are linked by a shared trace ID and parent-child relationships.

You create a tracer with provider.getTracer('react-app') and start spans with tracer.startSpan('component-mount'). After the work completes, call span.end() to record the end time. Always end spans — leaked spans waste memory and produce incomplete data in your observability backend.

Attributes enrich spans with contextual data: span.setAttribute('user.id', userId) or span.setAttribute('route', location.pathname). Attributes are searchable in your observability backend, enabling queries like "show all slow spans for user 42" or "show all errors on the /checkout route."

@opentelemetry/instrumentation-fetch monkey-patches the global fetch function to automatically create spans for every outgoing HTTP request. The span captures the URL, method, HTTP status code, and duration without any changes to your existing fetch calls.

When the fetch instrumentation creates a span for an outgoing request, it injects the W3C TraceContext traceparent header into the request. The receiving backend reads this header and continues the same trace, creating a connected trace that spans browser and server.

OTel initialization must happen before any components mount — typically in the app entry file (main.tsx) before the ReactDOM.createRoot call. Create the provider, register processors and exporters, and call provider.register() to make it the global TracerProvider.

Recording every user interaction in high-traffic apps generates enormous amounts of trace data. Configure a TraceIdRatioBased sampler (e.g., sample 10% of traces) in the TracerProvider to reduce volume. Always sample 100% of error traces using a ParentBased sampler to ensure no errors are missed.

Why is BatchSpanProcessor used instead of a SimpleSpanProcessor in browser applications?

The OpenTelemetry JavaScript SDK instruments browsers with TracerProvider, BatchSpanProcessor, and OTLPTraceExporter. Spans represent units of work enriched with attributes. Fetch instrumentation automatically creates spans for API calls and injects W3C TraceContext headers for end-to-end distributed tracing. Initialize early, sample appropriately, and always end spans to maintain clean trace data.