OpenTelemetry JavaScript Web distro for Uptrace

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 APIopen in new window and OpenTelemetry JS Metrics APIopen in new window.

Uptrace Web

uptrace-jsopen in new window is a thin wrapper over opentelemetry-jsopen in new window 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:

# 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://token@api.uptrace.dev/project_id) from the project settings page.

WARNING

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: 'https://token@api.uptrace.dev/project_id',

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

You can use the following options to configure Uptrace client.

OptionDescription
dsnA data source that is used to connect to uptrace.dev. For example, https://<token>@uptrace.dev/<project_id>.
serviceNameservice.name resource attribute. For example, myservice.
serviceVersionservice.version resource attribute. For example, 1.0.0.
deploymentEnvironmentdeployment.environment resource attribute. For example, production.
resourceAttributesAny other resource attributes.
resourceResource 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 varDescription
UPTRACE_DSNA data source that is used to connect to uptrace.dev. For example, https://<token>@uptrace.dev/<project_id>.
OTEL_RESOURCE_ATTRIBUTESKey-value pairs to be used as resource attributes. For example, service.name=myservice,service.version=1.0.0.
OTEL_SERVICE_NAME=myserviceSets the value of the service.name resource attribute. Takes precedence over OTEL_RESOURCE_ATTRIBUTES.
OTEL_PROPAGATORSPropagators to be used as a comma separated list. The default is tracecontext,baggage.

See OpenTelemetry documentationopen in new window 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 pluginsopen in new window for the full list of available instrumentations.

Instrumenting Vue.js 2.x

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

configureOpentelemetry({
  dsn: 'https://token@api.uptrace.dev/project_id',
})

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)
Last Updated: