@opentelemetry/sdk-trace-web

What is @opentelemetry/sdk-trace-web?

@opentelemetry/sdk-trace-web is a package that provides OpenTelemetry tracing capabilities specifically for web applications. It allows developers to capture and export trace data from web applications, which can be used for performance monitoring, debugging, and observability.

What are @opentelemetry/sdk-trace-web's main functionalities?

Initialize Tracer

This code initializes a tracer provider for web applications, sets up a span processor to export spans to the console, and registers the provider. The tracer can then be used to create and manage spans.

const { WebTracerProvider } = require('@opentelemetry/sdk-trace-web');
const { ConsoleSpanExporter, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');

const provider = new WebTracerProvider();
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
provider.register();

const tracer = provider.getTracer('example-tracer-web');

Create and End a Span

This code demonstrates how to create a span, simulate some work with a timeout, and then end the span. Spans represent units of work and are used to measure the time taken for operations.

const span = tracer.startSpan('example-span');
// Simulate some work
setTimeout(() => {
  span.end();
}, 1000);

Add Attributes to a Span

This code shows how to add attributes to a span. Attributes are key-value pairs that provide additional context about the span.

const span = tracer.startSpan('example-span');
span.setAttribute('key', 'value');
span.end();

Add Events to a Span

This code demonstrates how to add events to a span. Events are time-stamped annotations that provide additional information about the span.

const span = tracer.startSpan('example-span');
span.addEvent('event-name', { 'key': 'value' });
span.end();

Other packages similar to @opentelemetry/sdk-trace-web

jaeger-client

jaeger-client is a library for instrumenting applications with Jaeger tracing. It provides similar capabilities to @opentelemetry/sdk-trace-web, enabling developers to capture and export trace data. Like zipkin-js, jaeger-client is specific to the Jaeger tracing system, while @opentelemetry/sdk-trace-web is part of the more versatile OpenTelemetry project.

elastic-apm-js-base

elastic-apm-js-base is a library for instrumenting web applications with Elastic APM tracing. It offers similar functionality to @opentelemetry/sdk-trace-web, allowing developers to capture and export trace data to Elastic APM. Unlike @opentelemetry/sdk-trace-web, which is part of the OpenTelemetry project, elastic-apm-js-base is specific to the Elastic APM ecosystem.

README

OpenTelemetry Web SDK

This module provides automated instrumentation and tracing for Web applications.

For manual instrumentation see the @opentelemetry/sdk-trace-base package.

How does automatic tracing work

This package exposes a class WebTracerProvider that will be able to automatically trace things in Browser only.

See the example how to use it.

OpenTelemetry comes with a growing number of instrumentations for well know modules (see supported modules) and an API to create custom instrumentations (see the instrumentation developer guide).

Web Tracer currently supports one plugin for document load. Unlike Node Tracer (NodeTracerProvider), the plugins needs to be initialized and passed in configuration. The reason is to give user full control over which plugin will be bundled into web page.

You can choose to use the ZoneContextManager if you want to trace asynchronous operations. Please note that the ZoneContextManager does not work with JS code targeting ES2017+. In order to use the ZoneContextManager, please transpile back to ES2015.

Installation

npm install --save @opentelemetry/sdk-trace-web

Usage

import {
  ConsoleSpanExporter,
  SimpleSpanProcessor,
  WebTracerProvider,
} from '@opentelemetry/sdk-trace-web';
import { DocumentLoad } from '@opentelemetry/plugin-document-load';
import { ZoneContextManager } from '@opentelemetry/context-zone';
import { registerInstrumentations } from '@opentelemetry/instrumentation';

const provider = new WebTracerProvider({
  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())]
});

provider.register({
  // Changing default contextManager to use ZoneContextManager - supports asynchronous operations - optional
  contextManager: new ZoneContextManager(),
});

// Registering instrumentations / plugins
registerInstrumentations({
  instrumentations: [
    new DocumentLoad(),
  ],
});

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.

Changelog

1.28.0

:rocket: (Enhancement)

• feat(sdk-metrics, sdk-trace): add mergeResourceWithDefaults flag, which allows opting-out of resources getting merged with the default resource #4617

  • default: true (no change in behavior)
  • note: false will become the default behavior in the next major version in order to comply with specification requirements

• feat(sdk-trace-base): add spanProcessors property in TracerConfig interface. #5138 @david-luna

:bug: (Bug Fix)

• fix(sdk-metrics): await exports in PeriodicExportingMetricReader when async resource attributes have not yet settled #5119 @pichlermarc
• fix(sdk-trace): performance.now() may return the same value for consecutive calls #5150 @dyladan
• fix(sdk-trace-base): pass BatchSpanProcessor#forceFlush() errors on visibilitychange/pagehide to globalErrorHandler #5143 @pichlermarc
  • fixes a bug where switching browser tabs with a failing exporter would cause an unhandled error