OpenTelemetry for Real User Monitoring (RUM)

Set the configuration

Start by setting the options to be used by all the signals and the instrumentation code, as well as initializing the internal logger.

For this step, you need the following dependencies:

• @opentelemetry/api: All the packages are included. Each signal configuration uses it to register the providers for each signal.
• @opentelemetry/core: Contains core types and some utilities for the rest of the packages. It parses strings to the correct type.

To install the dependencies, run the following command:

npm install @opentelemetry/api @opentelemetry/core
		

After the dependencies are installed, configure the following options:

import { diag, DiagConsoleLogger } from '@opentelemetry/api';
import { diagLogLevelFromString } from '@opentelemetry/core';

// Set the configuration options
const OTEL_LOG_LEVEL = 'info';
const OTEL_EXPORTER_OTLP_ENDPOINT = 'https://proxy.example.com';
const OTEL_RESOURCE_ATTRIBUTES = {
  'service.name': 'my-web-app',
  'service.version': '1.2.3',
  'deployment.environment.name': 'qa',
  // You can add other attributes
};

// Set the log level for the OTEL components
// You can raise the level to "debug" if you want more details
diag.setLogger(
  new DiagConsoleLogger(),
  { logLevel: diagLogLevelFromString(OTEL_LOG_LEVEL) },
);
diag.info('OTEL bootstrap', config);
		

Define the resource

A resource is an entity that generates telemetry, with its characteristics captured in resource attributes. An example is a web application operating within a browser that produces telemetry data.

A standardized set of attributes is specified in Browser resource semantic conventions, which can be included alongside those outlined in the configuration section. OpenTelemetry offers resource detectors like browserDetector to help set these attributes like brands, mobile, and platform.

To define the resource, you need the following dependencies:

• @opentelemetry/resources: This package helps you to define and work with resources because a Resource is not a plain object and has some properties (like immutability) and constraints.
• @opentelemetry/browser-detector: Detectors help you to define a resource by querying the runtime and environment and resolving some attributes. In this case, the browser detector resolves the language, brands, and mobile attributes of the browser namespace.

To install the dependencies, run the following command:

npm install @opentelemetry/resources @opentelemetry/browser-detector
		

After the dependencies are installed, define the resource for your instrumentation with the following code:

import { resourceFromAttributes, detectResources } from '@opentelemetry/resources';
import { browserDetector } from '@opentelemetry/opentelemetry-browser-detector';

const detectedResources = detectResources({ detectors: [browserDetector] });
let resource = resourceFromAttributes(OTEL_RESOURCE_ATTRIBUTES);
resource = resource.merge(detectedResources);
		

(Optional) Configure tracing

Configure a TracerProvider to enable instrumentations to transmit traces and allow for the creation of custom spans. A TracerProvider requires several components:

• Resource: The resource to be associated with the spans created by the tracers. You defined this in the second step.
• Span Processor: A component that manages the spans generated by the tracers and forwards them to a SpanExporter. The exporter should be configured to direct data to an endpoint designated for traces.
• Span Exporter: Manages the transmission of spans to the Collector.
• Context Manager: A mechanism for managing the active Span context across asynchronous operations and threads. It ensures that when a new Span is created, it correctly identifies its parent Span.

For this step, you need the following dependencies:

• @opentelemetry/sdk-trace-base: This package contains all the core components to set up tracing regardless of the runtime they're running in (Node.js or browser).
• @opentelemetry/sdk-trace-web: This package contains a tracer provider that runs in web browsers.
• @opentelemetry/exporter-trace-otlp-http: This package contains the exporter for the HTTP/JSON protocol.
• @opentelemetry/context-zone: This package contains a context manager which uses on zone.js library.

npm install @opentelemetry/sdk-trace-base\
      @opentelemetry/sdk-trace-web\
      @opentelemetry/exporter-trace-otlp-http\
      @opentelemetry/context-zone
		

After the dependencies are installed, configure and register a TracerProvider with the following code:

import { trace } from '@opentelemetry/api';
import { ZoneContextManager } from '@opentelemetry/context-zone';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';

// Set the traces endpoint based on the config provided
const tracesEndpoint = `${OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces`;

// Set the tracer provider for instrumentations and calls to the API to start and end spans
const tracerProvider = new WebTracerProvider({
  resource,
  spanProcessors: [
    new BatchSpanProcessor(new OTLPTraceExporter({
      url: tracesEndpoint,
    })),
  ],
});
tracerProvider.register({ contextManager: new ZoneContextManager() });
		

Now you can use the OpenTelemetry API to get a tracer and start creating your own spans. Instrumentations are also using OpenTelemetry API to get tracers and send telemetry data. Registering intrumentations after having the tracer provider set up ensures they have the right tracers when requested to the API.

(Optional) Configure metrics

Similar to traces, configure a MeterProvider for metrics. A MeterProvider requires several components:

• Resource: The resource to be associated with the metrics created by the meters. You defined this in the second step.
• Metric Reader: Used to determine how often metrics are collected and what destination they should be exported to. In this case, use a PeriodicExportingMetricReader configured to collect and export metrics at a fixed interval.
• Metric Exporter: Responsible for serializing and sending the collected and aggregated metric data to a backend observability platform. Use the OTLP/HTTP exporter.

For this step, you need the following dependencies:

• @opentelemetry/sdk-metrics: This package contains all the required components to set up metrics.
• @opentelemetry/exporter-metrics-otlp-http: This package contains the exporter for the HTTP/JSON protocol.

To install the dependencies, run the following command:

npm install @opentelemetry/sdk-metrics @opentelemetry/exporter-metrics-otlp-http
		

After the dependencies are installed, configure and register a MeterProvider with the following code:

import { metrics } from '@opentelemetry/api';
import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';

// Set the metrics endpoint based on the config provided
const metricsEndpoint = `${OTEL_EXPORTER_OTLP_ENDPOINT}/v1/metrics`;

// Create metric reader to process metrics and export using OTLP
const metricReader = new PeriodicExportingMetricReader({
  exporter: new OTLPMetricExporter({ url: metricsEndpoint }),
});

// Create meter provider to send metrics
const meterProvider = new MeterProvider({
  resource: resource,
  readers: [metricReader],
});
metrics.setGlobalMeterProvider(meterProvider);
		

(Optional) Configure logs

Like traces and metrics, configure a LoggerProvider if you want to record relevant events that are happening in your application using the API or instrumentations. A LoggerProvider requires several components:

• Resource: The resource to be associated with the log records created by the loggers. You defined this in the second step.
• LogRecord Processor: A component that manages the log records generated by the loggers and forwards them to a LogExporter. The exporter should be configured to direct data to an endpoint designated for logs.
• Log Exporter: Manages the transmission of log records to the Collector.

For this step, you need the following dependencies:

• @opentelemetry/api-logs: This package contains the logs API. This API is not yet included in the generic API package because logs are still experimental.
• @opentelemetry/sdk-logs: This package contains all the required components to set up logs.
• @opentelemetry/exporter-logs-otlp-http: This package contains the exporter for the HTTP/JSON protocol.

To install the dependencies, run the following command:

npm install @opentelemetry/api-logs @opentelemetry/sdk-logs @opentelemetry/exporter-logs-otlp-http
		

After the dependencies are installed, configure and register a LoggerProvider with the following code:

import { logs, SeverityNumber } from '@opentelemetry/api-logs';
import { BatchLogRecordProcessor, LoggerProvider } from '@opentelemetry/sdk-logs';
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';

// Set the logs endpoint based on the config provided
const logsEndpoint = `${OTEL_EXPORTER_OTLP_ENDPOINT}/v1/logs`;

// Configure logging to send to the Collector
const logExporter = new OTLPLogExporter({ url: logsEndpoint });

const loggerProvider = new LoggerProvider({
  resource: resource,
  processors: [new BatchLogRecordProcessor(logExporter)]
});
logs.setGlobalLoggerProvider(loggerProvider);
		

Register the instrumentations

The final step for setting up Real User Monitoring (RUM) through OpenTelemetry is registering the instrumentations. Instrumentations are modules that automatically capture telemetry data, like network requests or DOM interactions, by using the OpenTelemetry API.

With the OpenTelemetry SDK, resource attributes, and exporters already configured, all telemetry data generated by these registered instrumentations is automatically processed and exported.

Install the following dependencies:

• @opentelemetry/instrumentation: This package contains the core components of instrumentations along with some utilities.
• @opentelemetry/auto-instrumentations-web: This package contains the more common instrumentations for web apps. Which are:
  • @opentelemetry/instrumentation-document-load: This instrumentation package measures the time it took the document to load and also the load timings of its resources. More info at instrumentation-document-load.
  • @opentelemetry/instrumentation-fetch: This instrumentation keeps track of your web application requests made through the Fetch API. More info at instrumentation-fetch.
  • @opentelemetry/instrumentation-xml-http-request: This instrumentation keeps track of your web application requests made through the XMLHttpRequest API. More info at instrumentation-xml-http-request.
  • @opentelemetry/instrumentation-user-interaction: This instrumentation measures user interactions in your web application. More info at instrumentation-user-interaction.
• @opentelemetry/instrumentation-long-task: This instrumentation is not part of the auto instrumentations package. It gathers information about long tasks being executed in your browser, helping to spot issues like unresponsive UI in your web application. More info at instrumentation-long-task.

To install the dependencies, run the following command:

npm install @opentelemetry/instrumentation\
      @opentelemetry/auto-instrumentations-web\
      @opentelemetry/instrumentation-long-task
		

After the dependencies are installed, configure and register instrumentations with the following code:

import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { getWebAutoInstrumentations } from '@opentelemetry/auto-instrumentations-web';
import { LongTaskInstrumentation } from '@opentelemetry/instrumentation-long-task';


// Register instrumentations
registerInstrumentations({
  instrumentations: [
    getWebAutoInstrumentations(),
    new LongTaskInstrumentation(),
  ],
});
		

Complete the setup script

All these pieces together give you a complete setup of all the signals for your web site or application. For convenience, it's better to have it in a separate file which can be named, for example, telemetry.js. This file should export a function that accepts the configuration allowing you to reuse the setup across different UIs.

To install all the dependencies needed for the complete setup, run the following command:

npm install @opentelemetry/api\
      @opentelemetry/core\
      @opentelemetry/resources\
      @opentelemetry/browser-detector\
      @opentelemetry/sdk-trace-base\
      @opentelemetry/sdk-trace-web\
      @opentelemetry/context-zone\
      @opentelemetry/exporter-trace-otlp-http\
      @opentelemetry/sdk-metrics\
      @opentelemetry/exporter-metrics-otlp-http\
      @opentelemetry/api-logs\
      @opentelemetry/sdk-logs\
      @opentelemetry/exporter-logs-otlp-http\
      @opentelemetry/instrumentation\
      @opentelemetry/auto-instrumentations-web\
      @opentelemetry/instrumentation-long-task
		

After the dependencies are installed, you can wrap the setup in a function with the following code:

// file: telemetry.js
import { diag, DiagConsoleLogger, trace, metrics } from '@opentelemetry/api';
import { diagLogLevelFromString } from '@opentelemetry/core';
import { resourceFromAttributes, detectResources } from '@opentelemetry/resources';
import { browserDetector } from '@opentelemetry/opentelemetry-browser-detector';
import { ZoneContextManager } from '@opentelemetry/context-zone';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
import { logs, SeverityNumber } from '@opentelemetry/api-logs';
import { BatchLogRecordProcessor, LoggerProvider } from '@opentelemetry/sdk-logs';
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { getWebAutoInstrumentations } from '@opentelemetry/auto-instrumentations-web';
import { LongTaskInstrumentation } from '@opentelemetry/instrumentation-long-task';

const initDone = Symbol('OTEL initialized');

// Expected properties of the config object:
// - logLevel
// - endpoint
// - resourceAttributes
export function initOpenTelemetry(config) {
  // To avoid multiple calls
  if (window[initDone]) {
    return;
  }
  window[initDone] = true;
  diag.setLogger(
    new DiagConsoleLogger(),
    { logLevel: diagLogLevelFromString(config.logLevel) },
  );
  diag.info('OTEL bootstrap', config);

  // Resource definition
  const detectedResources = detectResources({ detectors: [browserDetector] });
  const resource = resourceFromAttributes(config.resourceAttributes)
                              .merge(detectedResources);

  // Trace signal setup
  const tracesEndpoint = `${config.endpoint}/v1/traces`;
  const tracerProvider = new WebTracerProvider({
    resource,
    spanProcessors: [
      new BatchSpanProcessor(new OTLPTraceExporter({
        url: tracesEndpoint,
      })),
    ],
  });
  tracerProvider.register({ contextManager: new ZoneContextManager() })

  // Metrics signal setup
  const metricsEndpoint = `${config.endpoint}/v1/metrics`;
  const metricReader = new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({ url: metricsEndpoint }),
  });
  const meterProvider = new MeterProvider({
    resource: resource,
    readers: [metricReader],
  });
  metrics.setGlobalMeterProvider(meterProvider);

  // Logs signal setup
  const logsEndpoint = `${config.endpoint}/v1/logs`;
  const logExporter = new OTLPLogExporter({ url: logsEndpoint });

  const loggerProvider = new LoggerProvider({
    resource: resource,
    processors: [new BatchLogRecordProcessor(logExporter)]
  });
  logs.setGlobalLoggerProvider(loggerProvider);

  // Register instrumentations
  registerInstrumentations({
    instrumentations: [
      getWebAutoInstrumentations(),
      new LongTaskInstrumentation(),
    ],
  });
}