@opentelemetry/node

OpenTelemetry Node SDK

This module provides automated instrumentation and tracing for Node.js applications.

For manual instrumentation see the @opentelemetry/tracing package.

How does automated instrumentation work?

This package exposes a NodeTracerProvider that will automatically hook into the module loader of Node.js.

For this to work, please make sure that NodeTracerProvider is initialized before any other module of your application, (like http or express) is loaded.

OpenTelemetry comes with a growing number of instrumentation plugins for well know modules (see supported modules) and an API to create custom plugins (see the plugin developer guide).

Whenever a module is loaded NodeTracerProvider will check if a matching instrumentation plugin has been installed.

Please note: This module does not bundle any plugins. They need to be installed separately.

If the respective plugin was found, it will be used to patch the original module to add instrumentation code. This is done by wrapping all tracing-relevant functions.

This instrumentation code will automatically

• extract a trace-context identifier from inbound requests to allow distributed tracing (if applicable)
• make sure that this current trace-context is propagated while the transaction traverses an application (see @opentelemetry/context-base for an in-depth explanation)
• add this trace-context identifier to outbound requests to allow continuing the distributed trace on the next hop (if applicable)
• create and end spans

In short, this means that this module will use provided plugins to automatically instrument your application to produce spans and provide end-to-end tracing by just adding a few lines of code.

Creating custom spans on top of auto-instrumentation

Additionally to automated instrumentation, NodeTracerProvider exposes the same API as @opentelemetry/tracing, allowing creating custom spans if needed.

Installation

npm install --save @opentelemetry/api
npm install --save @opentelemetry/node

# Install instrumentation plugins
npm install --save @opentelemetry/plugin-http
npm install --save @opentelemetry/plugin-https

Usage

The following code will configure the NodeTracerProvider to instrument http using @opentelemetry/plugin-http.

const { NodeTracerProvider } = require('@opentelemetry/node');

// Create and configure NodeTracerProvider
const provider = new NodeTracerProvider({
  plugins: {
    http: {
      enabled: true,
      // You may use a package name or absolute path to the file.
      path: '@opentelemetry/plugin-http',
      // http plugin options
    }
  }
});

// Initialize the provider
provider.register()

// Your application code - http will automatically be instrumented if
// @opentelemetry/plugin-http is present
const http = require('http');

To enable instrumentation for all supported modules, create an instance of NodeTracerProvider without providing any plugin configuration to the constructor.

const { NodeTracerProvider } = require('@opentelemetry/node');

// Create and initialize NodeTracerProvider
const provider = new NodeTracerProvider();

// Initialize the provider
provider.register()

// Your application code
// ...

Examples

See how to automatically instrument http and gRPC using node-sdk.

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us on gitter

License

Apache 2.0 - See LICENSE for more information.

Changelog

0.8.0

Released 2020-05-12

:boom: Breaking Change

• opentelemetry-api, opentelemetry-metrics
  • #1001 fix: observers should not expose bind/unbind method (@legendecas)

:bug: (Bug Fix)

• opentelemetry-plugin-http
  • #984 fix(http-plugin): strip otel custom http header #983 (@vmarchaud)
• opentelemetry-core
  • #1021 fix: left pad short b3 trace identifiers (@dyladan)
• opentelemetry-plugin-xml-http-reques
  • #1002 fix(opentelemetry-plugin-xml-http-request): define span kind as CLIENT for xmlhttprequests (@ivansenic)
• opentelemetry-plugin-grpc
  • #1005 fix: add missing error status handler (@markwolff)
• opentelemetry-exporter-collector
  • #1008 fix: permission denied error when cloning submodules (@sleighzy)

:rocket: (Enhancement)

• opentelemetry-exporter-zipkin, opentelemetry-plugin-http, opentelemetry-tracing
  • #1037 fix(tracing): span processor should receive a readable span as parameters (@legendecas)
• opentelemetry-tracing
  • #1024 fix: multi span processor should flush child span processors (@legendecas)
• opentelemetry-metrics, opentelemetry-tracing
  • #1015 fix: prevent duplicated resource creation (@legendecas)
• opentelemetry-metrics
  • #1014 feat(metrics): use MetricDescriptor to determine aggregator #989 (@vmarchaud)
• opentelemetry-plugin-http
  • #948 feat(http-plugin): add options to disable new spans if no parent (@vmarchaud)
• opentelemetry-api, opentelemetry-node, opentelemetry-plugin-grpc, opentelemetry-plugin-http, opentelemetry-plugin-https, opentelemetry-plugin-xml-http-request, opentelemetry-tracing, opentelemetry-web
  • #943 Use global API instances (@dyladan)
• opentelemetry-api
  • #1016 refactor: normalize namespace import name for @opentelemetry/api (@legendecas)
• opentelemetry-core, opentelemetry-base
  • #991 refactor: merge opentelemetry-base to opentelemetry-core (@legendecas)
• opentelemetry-core
  • #981 chore: splitting BasePlugin into browser and node (@obecny)

:books: (Refine Doc)

• Other
  • #1003 chore: test on node 14 (@dyladan)
  • #990 fix(opentracing-shim): update opentracing shim example (@sleighzy)

Committers: 7

• legendecas (@legendecas)
• Valentin Marchaud (@vmarchaud)
• Daniel Dyla (@dyladan)
• Ivan Senic (@ivansenic)
• Mark Wolff (@markwolff)
• Simon Leigh (@sleighzy)
• Bartlomiej Obecny (@obecny)