@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 auto instrumentation works

This package exposes a NodeTracerProvider. For loading plugins / instrumentations please use registerInstrumentations function from opentelemetry-instrumentation

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

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

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

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/instrumentation-http
# and for example one additional
npm install --save instrumentation-graphql

Usage

The following code will configure the NodeTracerProvider to instrument http (and any other installed supported modules) using @opentelemetry/plugin-http.

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

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

// Initialize the provider
provider.register();

// register and load instrumentation and old plugins - old plugins will be loaded automatically as previously
// but instrumentations needs to be added
registerInstrumentations({
  tracerProvider: provider,
});

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

Instrumentation / Plugin configuration

User supplied plugin configuration is merged with the default plugin configuration. Furthermore, custom plugins that are configured are implicitly enabled just as default plugins are.

In the following example:

• the default express plugin is disabled
• the http plugin has a custom config for a requestHook
• the customPlugin is loaded from the user supplied path
• all default plugins are still loaded if installed.

const { GraphQLInstrumentation } = require('@opentelemetry/instrumentation-graphql');

const provider = new NodeTracerProvider();

// register and load instrumentation and old plugins - old plugins will be loaded automatically as previously
// but instrumentations needs to be added
registerInstrumentations({
  tracerProvider: provider,
  instrumentations: [
    new GraphQLInstrumentation(),
    // for older plugins you can just copy paste the old configuration
    {
      plugins: {
        express: {
          enabled: false,
        },
        http: {
          requestHook: (span, request) => {
            span.setAttribute("custom request hook attribute", "request");
          },
        },
        customPlugin: {
          path: "/path/to/custom/module",
        },
      },
    }
  ],
});

Disable Plugins with Environment Variables

Plugins can be disabled without modifying and redeploying code. OTEL_NO_PATCH_MODULES accepts a comma separated list of module names to disabled specific plugins. The names should match what you use to require the module into your application. For example, OTEL_NO_PATCH_MODULES=pg,https will disable the postgres plugin and the https plugin. To disable all plugins, set the environment variable to *.

Examples

See how to automatically instrument http and gRPC / grpc-js 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 in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.

Changelog

0.18.0

:boom: Breaking Change

• opentelemetry-resources
  • #1975 fix: specification compliant resource collision precedence (@lonewolf3739)

:rocket: (Enhancement)

• opentelemetry-semantic-conventions
  • #1976 feat(semantic-conventions): add missing RpcAttributes from spec (@blumamir)

:bug: (Bug Fix)

• opentelemetry-exporter-collector-grpc, opentelemetry-exporter-collector
  • #1938 fix(exporter-collector): wrong data type for numbers (@kudlatyamroth)
• opentelemetry-instrumentation-http, opentelemetry-plugin-http
  • #1939 fix: use socket from the request (@mzahor)
• opentelemetry-context-async-hooks
  • #1937 fix: isolate binding EventEmitter (@Flarna)

:books: (Refine Doc)

• #1973 docs(readme): fix @opentelemetry/instrumentation-http link (@Hongbo-Miao)
• #1941 fix: update readme upgrade guidelines version setting (@MSNev)

:house: (Internal)

• opentelemetry-api-metrics, opentelemetry-context-async-hooks, opentelemetry-context-zone-peer-dep, opentelemetry-core, opentelemetry-exporter-collector-grpc, opentelemetry-exporter-collector-proto, opentelemetry-exporter-collector, opentelemetry-exporter-jaeger, opentelemetry-exporter-prometheus, opentelemetry-exporter-zipkin, opentelemetry-grpc-utils, opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-grpc, opentelemetry-instrumentation-http, opentelemetry-instrumentation-xml-http-request, opentelemetry-instrumentation, opentelemetry-metrics, opentelemetry-node, opentelemetry-plugin-grpc-js, opentelemetry-plugin-grpc, opentelemetry-plugin-http, opentelemetry-plugin-https, opentelemetry-propagator-b3, opentelemetry-resource-detector-aws, opentelemetry-resource-detector-gcp, opentelemetry-resources, opentelemetry-sdk-node, opentelemetry-shim-opentracing, opentelemetry-tracing, opentelemetry-web
  • #1977 chore: update API to 0.18.0 (@Flarna)
• Other
  • #1960 chore: updating current state of compatibility matrix (@obecny)
• opentelemetry-api-metrics, opentelemetry-api, opentelemetry-context-async-hooks, opentelemetry-context-base, opentelemetry-context-zone-peer-dep, opentelemetry-core, opentelemetry-exporter-collector-grpc, opentelemetry-exporter-collector-proto, opentelemetry-exporter-collector, opentelemetry-exporter-jaeger, opentelemetry-exporter-prometheus, opentelemetry-exporter-zipkin, opentelemetry-grpc-utils, opentelemetry-instrumentation-fetch, opentelemetry-instrumentation-grpc, opentelemetry-instrumentation-http, opentelemetry-instrumentation-xml-http-request, opentelemetry-instrumentation, opentelemetry-metrics, opentelemetry-node, opentelemetry-plugin-grpc-js, opentelemetry-plugin-grpc, opentelemetry-plugin-http, opentelemetry-plugin-https, opentelemetry-propagator-b3, opentelemetry-resource-detector-aws, opentelemetry-resource-detector-gcp, opentelemetry-resources, opentelemetry-sdk-node, opentelemetry-shim-opentracing, opentelemetry-tracing, opentelemetry-web
  • #1942 chore: remove API and context-base (@dyladan)
• opentelemetry-core, opentelemetry-exporter-collector, opentelemetry-instrumentation-http, opentelemetry-metrics, opentelemetry-plugin-http
  • #1922 chore: lint on shadowing in non-test sources, fix a few of them (@johnbley)

Committers: 10

• Amir Blum (@blumamir)
• Bartlomiej Obecny (@obecny)
• Daniel Dyla (@dyladan)
• Gerhard Stöbich (@Flarna)
• Hongbo Miao (@Hongbo-Miao)
• John Bley (@johnbley)
• Karol Fuksiewicz (@kudlatyamroth)
• Marian Zagoruiko (@mzahor)
• Nev (@MSNev)
• Srikanth Chekuri (@lonewolf3739)