@opentelemetry/sdk-trace-node

What is @opentelemetry/sdk-trace-node?

The @opentelemetry/sdk-trace-node package is part of the OpenTelemetry JavaScript ecosystem and provides a Node.js SDK for tracing. It allows developers to collect and export trace data in their Node.js applications to analyze application performance and troubleshoot issues. The SDK supports various exporters and can be configured to send trace data to different backends for monitoring.

What are @opentelemetry/sdk-trace-node's main functionalities?

Initializing Tracing

This code initializes the Node.js tracing provider and sets up a simple span processor with a console exporter, which will print the trace data to the console.

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
const { ConsoleSpanExporter } = require('@opentelemetry/exporter-console');

const provider = new NodeTracerProvider();
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
provider.register();

Configuring Exporters

This code snippet demonstrates how to configure the NodeTracerProvider to use the Jaeger exporter, which sends trace data to a Jaeger backend for analysis.

const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');

const provider = new NodeTracerProvider();
const jaegerExporter = new JaegerExporter({
  serviceName: 'my-service',
});
provider.addSpanProcessor(new SimpleSpanProcessor(jaegerExporter));
provider.register();

Automatic Instrumentation

This code sets up automatic instrumentation for Node.js applications, which automatically collects trace data from supported libraries without manual instrumentation.

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');

const provider = new NodeTracerProvider();
provider.register();

require('@opentelemetry/instrumentation').registerInstrumentations({
  instrumentations: [getNodeAutoInstrumentations()],
});

Other packages similar to @opentelemetry/sdk-trace-node

dd-trace

The dd-trace package is Datadog's APM tracing library for Node.js. It provides automatic instrumentation for popular frameworks and libraries. Compared to @opentelemetry/sdk-trace-node, dd-trace is more tightly integrated with Datadog's monitoring services but less vendor-neutral.

elastic-apm-node

Elastic APM Node.js Agent is Elastic's solution for tracing and monitoring Node.js applications. It automatically instruments the code and captures errors and transactions. Similar to @opentelemetry/sdk-trace-node, it provides detailed performance insights but is designed to work seamlessly with the Elastic Stack.

newrelic

New Relic's APM Agent for Node.js is a monitoring and tracing tool that provides deep insights into application performance. It differs from @opentelemetry/sdk-trace-node in that it is part of New Relic's proprietary APM platform, offering extensive integration with their suite of monitoring tools.

README

OpenTelemetry Node SDK

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

For manual instrumentation see the @opentelemetry/sdk-trace-base package.

How auto instrumentation works

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

OpenTelemetry comes with a growing number of instrumentation plugins for well known 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 context document in @opentelemetry/api 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/sdk-trace-base, allowing creating custom spans if needed.

Installation

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-trace-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/sdk-trace-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({
});

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

Instrumentation configuration

In the following example:

• the express instrumentation is enabled
• the http instrumentation has a custom config for a requestHook

const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-express');

const provider = new NodeTracerProvider();
provider.register();

// register and load instrumentation and old plugins - old plugins will be loaded automatically as previously
// but instrumentations needs to be added
registerInstrumentations({
  instrumentations: [
    new ExpressInstrumentation(),
    new HttpInstrumentation({
        requestHook: (span, request) => {
          span.setAttribute("custom request hook attribute", "request");
        },
    }),
  ],
});

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

1.10.0

:rocket: (Enhancement)

• feat(resource): create sync resource with some attributes that resolve asynchronously #3460 @samimusallam
• feat: collect host id for non-cloud environments #3575 @mwear
• feat (api-logs): separate Events API into its own package 3550 @martinkuba
• feat(sdk-metrics): apply binary search in histogram recording #3539 @legendecas
• perf(propagator-jaeger): improve deserializeSpanContext performance #3541 @doochik
• feat: support TraceState in SamplingResult #3530 @raphael-theriault-swi
• feat(sdk-trace-base): add diagnostic logging when spans are dropped #3610 @neoeinstein
• feat: add unit to view instrument selection criteria #3647 @jlabatut
• feat(tracing): expose dropped counts for attributes, events and links on span #3576 @mohitk05

:bug: (Bug Fix)

• fix(core): added falsy check to make otel core work with browser where webpack config had process as false or null #3613 @ravindra-dyte
• fix(instrumentation-http): include query params in http.target #3646 @kobi-co

:books: (Refine Doc)

• chore: update http example #3651 @JamieDanielson

:house: (Internal)

• chore(exporter-jaeger): deprecate jaeger exporter #3585 @pichlermarc
• fix(sdk-metrics): fix flaky LastValueAggregator test by using fake timer #3587 @pichlermarc
• fix(test): fix failing tests by preventing source-map generation #3642 @pichlermarc