Getting Started   •   API and SDK Reference

Contributing   •   Examples

About this project

This is the JavaScript version of OpenTelemetry, a framework for collecting traces, metrics, and logs from applications.

Quick Start

Much of OpenTelemetry JS documentation is written assuming the compiled application is run as CommonJS. For more details on ECMAScript Modules vs CommonJS, refer to esm-support.

The following describes how to set up tracing for a basic web application. For more detailed documentation, see the website at .

Installation

Dependencies with the latest tag on NPM should be compatible with each other. See the version compatibility matrix below for more information.

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-node
npm install --save @opentelemetry/auto-instrumentations-node

Note: auto-instrumentations-node is a meta package from opentelemetry-js-contrib that provides a simple way to initialize multiple Node.js instrumentations.

Set up Tracing

// tracing.js

'use strict'

const process = require('process');
const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { ConsoleSpanExporter } = require('@opentelemetry/sdk-trace');
const { resourceFromAttributes } = require('@opentelemetry/resources');
const { ATTR_SERVICE_NAME } = require('@opentelemetry/semantic-conventions');

// configure the SDK to export telemetry data to the console
// enable all auto-instrumentations from the meta package
const traceExporter = new ConsoleSpanExporter();
const sdk = new opentelemetry.NodeSDK({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: 'my-service',
  }),
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()]
});

// initialize the SDK and register with the OpenTelemetry API
// this enables the API to record telemetry
sdk.start();

// gracefully shut down the SDK on process exit
process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.log('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

Run Your Application

node -r ./tracing.js app.js

The above example will emit auto-instrumented telemetry about your Node.js application to the console. For a more in-depth example, see the Getting Started Guide.

Debugging The Setup

It's possible that an application instrumented as outlined above may not be behaving in an expected manner. For example, if the application is meant to be sending data to an Open Telemetry collector, that collector may not be receiving any data. Insight into such issues can be gained by enabling a diagnostics logger:

// Added as additional configuration to tracing.js

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

Library Author

If you are a library author looking to build OpenTelemetry into your library, please see [the documentation][docs]. As a library author, it is important that you only depend on properties and methods published on the public API. If you use any properties or methods from the SDK that are not officially a part of the public API, your library may break if an application owner uses a different SDK implementation.

Supported Runtimes

Node Support

Only Node.js Active or Maintenance LTS versions are supported. Previous versions of node may work, but they are not tested by OpenTelemetry and they are not guaranteed to work.

Browser Support

[!IMPORTANT] Client instrumentation for the browser is experimental and mostly unspecified. If you are interested in helping out, get in touch with the [Client Instrumentation SIG][client-instrumentation-sig].

Rather than define versions of specific browsers / runtimes, OpenTelemetry sets the minimum supported version based on the underlying language features used.

The current minimum language feature support is set as [ECMAScript 2022](https://262.ecma-international.org/13.0/