OpenTelemetry JavaScript for browsers

This document explains how to configure OpenTelemetry JavaScript SDK for Web to export spans and metrics from browsers to Uptrace using OTLP/HTTP.

If you need to monitor JavaScript Web applications, using Sentry SDK instead of OpenTelemetry JS might provide a better result.

To learn about OpenTelemetry API, see OpenTelemetry JS Tracing API and OpenTelemetry JS Metrics API.

Uptrace Web

uptrace-js is a thin wrapper over opentelemetry-js that configures OpenTelemetry SDK to export data to Uptrace. It does not add any new functionality and is provided only for your convenience.

To install @uptrace/web:

shell

# npm
npm install @uptrace/web --save-dev

# yarn
yarn add @uptrace/web --dev

Configuration

You can configure Uptrace client using a DSN (Data Source Name, for example, https://<secret>@api.uptrace.dev?grpc=4317) from the project settings page.

You must call configureOpentelemetry as early as possible and before importing other packages, because OpenTelemetry SDK must patch libraries before you import them.

import { configureOpentelemetry } from '@uptrace/web'

// configureOpentelemetry automatically setups window.onerror handler.
configureOpentelemetry({
  // Set dsn or UPTRACE_DSN env var.
  dsn: '<FIXME>',

  serviceName: 'myservice',
  serviceVersion: '1.0.0',
})

You can use the following options to configure Uptrace client.

Option	Description
`dsn`	A data source that is used to connect to uptrace.dev. For example, `https://<token>@uptrace.dev/<project_id>`.
`serviceName`	`service.name` resource attribute. For example, `myservice`.
`serviceVersion`	`service.version` resource attribute. For example, `1.0.0`.
`deploymentEnvironment`	`deployment.environment` resource attribute. For example, `production`.
`resourceAttributes`	Any other resource attributes.
`resource`	Resource contains attributes representing an entity that produces telemetry. Resource attributes are copied to all spans and events.

You can also use environment variables to configure the client:

Env var	Description
`UPTRACE_DSN`	A data source that is used to connect to uptrace.dev. For example, `https://<token>@uptrace.dev/<project_id>`.
`OTEL_RESOURCE_ATTRIBUTES`	Key-value pairs to be used as resource attributes. For example, `service.name=myservice,service.version=1.0.0`.
`OTEL_SERVICE_NAME=myservice`	Sets the value of the service.name resource attribute. Takes precedence over `OTEL_RESOURCE_ATTRIBUTES`.
`OTEL_PROPAGATORS`	Propagators to be used as a comma separated list. The default is `tracecontext,baggage`.

See OpenTelemetry documentation for details.

Context manager

ZoneContextManager is a context manager implementation based on the Zone.js library. It enables context propagation within the application using zones.

To install Zone.js context manager:

npm install --save @opentelemetry/context-zone

To use Zone.js context manager:

import { ZoneContextManager } from '@opentelemetry/context-zone'

configureOpentelemetry({
  contextManager: new ZoneContextManager(),
})

Instrumentations

You can use configureOpentelemetry to register instrumentations like this:

import { FetchInstrumentation } from '@opentelemetry/instrumentation-fetch'

configureOpentelemetry({
  instrumentations: [new FetchInstrumentation()],
})

Or use registerInstrumentations directly:

import { FetchInstrumentation } from '@opentelemetry/instrumentation-fetch'
import { registerInstrumentations } from '@opentelemetry/instrumentation'

registerInstrumentations({
  instrumentations: [new FetchInstrumentation()],
})

See opentelemetry-js web plugins for the full list of available instrumentations.

Instrumenting Vue.js 2.x

import Vue from 'vue'
import { configureOpentelemetry, reportException } from '@uptrace/web'

configureOpentelemetry({
  dsn: '<FIXME>',
})

Vue.config.errorHandler = (err, vm, info) => {
  reportException(err, {
    vm: vm,
    info: info,
  })
}

Troubleshooting

If OpenTelemetry is not working as expected, you can enable verbose logging to check for potential issues:

const { DiagConsoleLogger, DiagLogLevel, diag } = require('@opentelemetry/api')
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG)

Node.jsComprehensive guide for setting up and using OpenTelemetry in Node.js applications to export telemetry data using OTLP/HTTP

Tracing API