Setup and Install OpenTelemetry Node.js

Get up and running with OpenTelemetry in just a few quick steps! The setup process consists of two phases--getting OpenTelemetry installed and configured, and then validating that configuration to ensure that data is being sent as expected. This guide explains how to download, install, and run OpenTelemetry in Node.js.

Requirements

  • Node.js version 12 or newer
  • An app to add OpenTelemetry to. You can use this example application or bring your own.
  • A Lightstep account, or another OpenTelemetry backend.

Need an account? Create a free Lightstep account here.

Installation

To install OpenTelemetry, we recommend our handy OTel-Launcher, which simplifies the process.

npm install lightstep-opentelemetry-launcher-node --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.

The full list of configuration options can be found in the README.

const { lightstep, opentelemetry } = require('lightstep-opentelemetry-launcher-node');

const sdk = lightstep.configureOpenTelemetry({
  accessToken: 'YOUR_ACCESS_TOKEN',
  serviceName: 'example-service',
});

sdk.start().then(() => {
  // All of your application code and any imports that should leverage
  // OpenTelemetry automatic instrumentation must go here.
});

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

Set an environment variable to run the OpenTelemetry launcher in debug mode, where it logs details about the configuration and emitted spans:

export OTEL_LOG_LEVEL=debug

The output may be very verbose with some benign errors. Early in the console output, look for logs about the configuration and check that your access token is correct. Next, look for lines like the ones below, which are emitted when spans are emitted to Lightstep.

{
  "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]
    }
  ]
}

Running short applications (Lambda/Serverless/etc)

If your application exits quickly after startup, you may need to explicitly shutdown the tracer to ensure that all spans are flushed:

opentelemetry.trace.getTracer('your_tracer_name').getActiveSpanProcessor().shutdown()