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.
OpenTelemetry Node SDK
This module provides automated instrumentation and tracing for Node.js applications.
For manual instrumentation see the
@opentelemetry/sdk-trace-base package.
Note: 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.
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
npm install --save @opentelemetry/instrumentation-http
npm install --save @opentelemetry/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');
const provider = new NodeTracerProvider();
provider.register();
registerInstrumentations({
});
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();
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
License
Apache 2.0 - See LICENSE for more information.