@opentelemetry/node

OpenTelemetry Node

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 NodeTracer that will automatically hook into the module loader of Node.js.

For this to work, please make sure that NodeTracer 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 NodeTracer 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/opentelemetry-scope-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, NodeTracer exposes the same API as @opentelemetry/tracing, allowing creating custom spans if needed.

Installation

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

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

Usage

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

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

// Create and configure NodeTracer
const tracer = new NodeTracer({
  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 tracer
opentelemetry.initGlobalTracer(tracer);

// 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 NodeTracer without providing any plugin configuration to the constructor.

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

// Create and initialize NodeTracer
const tracer = new NodeTracer();

// Initialize the tracer
opentelemetry.initGlobalTracer(tracer);

// 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.3.0

Released 2019-12-13

:rocket: (Enhancement)

• opentelemetry-core, opentelemetry-node, opentelemetry-plugin-dns, opentelemetry-plugin-document-load, opentelemetry-plugin-grpc, opentelemetry-plugin-postgres, opentelemetry-plugin-redis, opentelemetry-tracing, opentelemetry-types
  • #569 chore: allow parent span to be null
• opentelemetry-plugin-document-load
  • #546 chore: fixing issue when metric time is 0 in document-load plugin
  • #469 chore: fixing problem with load event and performance for loadend
• opentelemetry-plugin-http, opentelemetry-plugin-https
  • #548 fix(plugin-http): adapt to current @types/node
• Other
  • #510 chore(circleci): remove duplicate compile step
  • #514 ci: enumerate caching paths manually
  • #470 chore: remove examples from lerna packages
• opentelemetry-core, opentelemetry-metrics, opentelemetry-types
  • #507 feat: direct calling of metric instruments
  • #517 chore: update dependencies gts and codecov
  • #497 chore: bump typescript version to ^3.7.2
• opentelemetry-metrics
  • #475 add shutdown method on MetricExporter interface
• opentelemetry-core, opentelemetry-plugin-document-load, opentelemetry-tracing, opentelemetry-web
  • #466 chore: fixing coverage for karma using istanbul

:bug: (Bug Fix)

• opentelemetry-exporter-jaeger
  • #609 Jaeger no flush interval
• opentelemetry-plugin-dns
  • #613 fix(plugin-dns): remove from default plugin list
• opentelemetry-plugin-http
  • #589 fix(plugin-http): correct handling of WHATWG urls
  • #580 fix(plugin-http): http.url attribute
• opentelemetry-shim-opentracing
  • #577 fix: add missing main in package.json
• opentelemetry-exporter-zipkin
  • #526 fix: zipkin-exporter: don't export after shutdown
• opentelemetry-plugin-grpc
  • #487 fix(grpc): use correct supportedVersions
• opentelemetry-core
  • #472 fix(core): add missing semver dependency

:books: (Refine Doc)

• Other
  • #574 chore: add CHANGELOG.md
  • #575 Add exporter guide
  • #534 feat: add redis plugin example
  • #562 chore(web-example): Added a README for the existing example
  • #537 examples(tracing): add multi exporter example
  • #484 chore: update README for new milestones
• opentelemetry-plugin-mongodb-core
  • #564 docs: add usage for mongodb-core plugin #543)
• opentelemetry-metrics
  • #490 chore: update metrics README
• opentelemetry-plugin-redis
  • #551 chore: fix minor typo
• opentelemetry-exporter-prometheus
  • #521 chore: update prometheus exporter readme with usage and links
• opentelemetry-types
  • #512 chore: minor name change
• opentelemetry-plugin-postgres
  • #473 chore(plugin): postgres-pool plugin skeleton

:sparkles: (Feature)

• opentelemetry-core, opentelemetry-exporter-collector
  • #552 Collector exporter
• opentelemetry-node, opentelemetry-plugin-mysql
  • #525 feat: mysql support
• opentelemetry-plugin-redis
  • #503 feat(plugin): implement redis plugin
• opentelemetry-plugin-mongodb-core
  • #205 feat: add mongodb plugin
• opentelemetry-exporter-prometheus
  • #483 feat: Add prometheus exporter
• opentelemetry-metrics
  • #500 feat: add ConsoleMetricExporter
  • #468 feat: validate metric names
• opentelemetry-scope-zone-peer-dep, opentelemetry-scope-zone, opentelemetry-web
  • #461 feat(scope-zone): new scope manager to support async operations in web
• opentelemetry-core, opentelemetry-plugin-document-load
  • #477 feat(traceparent): setting parent span from server
• opentelemetry-core, opentelemetry-metrics, opentelemetry-types
  • #463 feat: implement labelset
• opentelemetry-metrics, opentelemetry-types
  • #437 feat(metrics): add registerMetric and getMetrics