Setup and Install OpenTelemetry in the Browser

This Quick Start shows you how to use OpenTelemetry in your browser to:

  • Configure a tracer
  • Generate trace data
  • Propagate context over HTTP
  • Export the trace data to the console and to the Lightstep
  • Enable auto instrumentation for document load
  • Enable auto instrumentation for button any XMLHttpRequest

The full code for the example in this guide can be found here.

Requirements

  • An up to date modern browser.
  • A Lightstep account, or another OpenTelemetry backend.

Need an account? Create a free Lightstep account here.

Installation

To use OpenTelemetry, you need to install the API, SDK, span processor and exporter packages. The version of the SDK and API used in this guide is 0.5.1, the most current version as of writing.

npm install @opentelemetry/api @opentelemetry/web @opentelemetry/tracing --save

Run OpenTelemetry

Once you've downloaded the launcher, you can run OpenTelemetry using the following basic configuration.

LS Note: When connecting to Lightstep, a project Access Token is required.

  1. Import OpenTelemetry and create a tracer configured to send data to the console, saving it as tracer.js.
// this will be needed to get a tracer
import opentelemetry from '@opentelemetry/api';
// tracer provider for web
import { WebTracerProvider } from '@opentelemetry/web';
// and an exporter with span processor
import {
  SimpleSpanProcessor,
} from '@opentelemetry/tracing';
import { CollectorTraceExporter } from '@opentelemetry/exporter-collector';

// Create a provider for activating and tracking spans
const tracerProvider = new WebTracerProvider();

// Connect to Lightsstep by configuring the exporter with your endpoint and access token.
tracerProvider.addSpanProcessor(new SimpleSpanProcessor(new CollectorTraceExporter({
  url: 'https://ingest.lightstep.com:443/api/v2/otel/trace',
  headers: {
    'Lightstep-Access-Token': 'YOUR_TOKEN'
  }
})));

// Register the tracer
tracerProvider.register();
  1. Load the tracer into your HTML document.
<script type="text/javascript" src="tracer.js"></script>

Validate Installation

With your application running, you can now verify that you’ve installed OpenTelemetry correctly by confirming that telemetry data is being reported to your observability backend.

To do this, you need to make sure that your application is actually generating data. Applications will generally not produce traces unless they are being interacted with, and opentelemetry will often buffer data before sending it. So it may take some amount of time and interaction before your application data begins to appear in your backend..

Validate your traces in Lightstep:

  1. Trigger an action in your app that generates a web request.
  2. In Lightstep, click on the Explorer in the sidebar.
  3. Refresh your query until you see traces.
  4. View the traces and verify that important aspects of your application are captured by the trace data.

Library and Framework Support

OpenTelemetry automatically provides instrumentation for a large number of libraries and frameworks, right out of the box.

The full list of supported plugins can be found in the README.

OpenTracing Support

The OpenTracing shim allows existing OpenTracing instrumentation to report to the OpenTelemetry SDK. OpenTracing support is not enabled by default. Instructions for enabling the shim can be found in the README.

Read more about upgrading to OpenTelemetry in our OpenTracing Migration Guide.

Troubleshooting

Logging to the console

To log to the console, add the ConsoleExporter in to your tracer setup.

import {
  ConsoleSpanExporter,
} from '@opentelemetry/tracing';

// after you have created your TracerProvider, create a ConsoleExporter and add it as a SpanProcessor
tracerProvider.addSpanProcessor(new ConsoleSpanExporter())

If your implementation is creating spans, you will now be able to see them in the console:

{
  "traceId": "985b66d592a1299f7d12ebca56ca1fe3",
  "parentId": "8d62a70aa335a227",
  "name": "bar",
  "id": "17ada85c3d55376a",
  "kind": 0,
  "timestamp": 1685674607399000,
  "duration": 299,
  "attributes": {},
  "status": { "code": 0 },
  "events": []
}
{
  "traceId": "985b66d592a1299f7d12ebca56ca1fe3",
  "name": "foo",
  "id": "8d62a70aa335a227",
  "kind": 0,
  "timestamp": 1585130342183948,
  "duration": 315,
  "attributes": {
    "name": "value"
  },
  "status": { "code": 0 },
  "events": [
    {
      "name": "event in foo",
      "time": [1585130342, 184213041]
    }
  ]
}