OpenTelemetry SDK for Node.js
Note: This is an experimental package under active development. New releases may include breaking changes.
This package provides the full OpenTelemetry SDK for Node.js including tracing and metrics.
Quick Start
To get started you need to install @opentelemetry/sdk-node
, a metrics and/or tracing exporter, and any appropriate instrumentation for the node modules used by your application.
Installation
$
$ npm install @opentelemetry/sdk-node
$
$ npm install \
@opentelemetry/exporter-jaeger \
@opentelemetry/exporter-prometheus \
@opentelemetry/instrumentation-http
$
$ npm install @opentelemetry/auto-instrumentations-node
Note: this example is for Node.js. See examples/opentelemetry-web for a browser example.
Initialize the SDK
Before any other module in your application is loaded, you must initialize the SDK.
If you fail to initialize the SDK or initialize it too late, no-op implementations will be provided to any library which acquires a tracer or meter from the API.
This example uses Jaeger and Prometheus, but exporters exist for other tracing backends.
As shown in the installation instructions, exporters passed to the SDK must be installed alongside @opentelemetry/sdk-node
.
const opentelemetry = require("@opentelemetry/sdk-node");
const { JaegerExporter } = require("@opentelemetry/exporter-jaeger");
const { PrometheusExporter } = require("@opentelemetry/exporter-prometheus");
const {
getNodeAutoInstrumentations,
} = require("@opentelemetry/auto-instrumentations-node");
const jaegerExporter = new JaegerExporter();
const prometheusExporter = new PrometheusExporter({ startServer: true });
const sdk = new opentelemetry.NodeSDK({
traceExporter: jaegerExporter,
metricReader: prometheusExporter,
instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();
const process = require("process");
process.on("SIGTERM", () => {
sdk
.shutdown()
.then(
() => console.log("SDK shut down successfully"),
(err) => console.log("Error shutting down SDK", err)
)
.finally(() => process.exit(0));
});
Configuration
Below is a full list of configuration options which may be passed into the NodeSDK
constructor;
autoDetectResources
Detect resources automatically from the environment using the default resource detectors. Default true
.
contextManager
Use a custom context manager. Default: AsyncHooksContextManager
textMapPropagator
Use a custom propagator. Default: CompositePropagator using W3C Trace Context and Baggage
metricReader
Add a MetricReader
that will be passed to the MeterProvider
. If metricReader
is not configured,
the metrics SDK will not be initialized and registered.
views
A list of views to be passed to the MeterProvider
.
Accepts an array of View-instances.
This parameter can be used to configure explicit bucket sizes of histogram metrics.
instrumentations
Configure instrumentations. By default none of the instrumentation is enabled,
if you want to enable them you can use either metapackage
or configure each instrumentation individually.
resource
Configure a resource. Resources may also be detected by using the autoDetectResources
method of the SDK.
resourceDetectors
Configure resource detectors. By default, the resource detectors are [envDetector, processDetector].
NOTE: In order to enable the detection, the parameter autoDetectResources
has to be true
.
sampler
Configure a custom sampler. By default, all traces will be sampled.
spanProcessor
traceExporter
Configure a trace exporter. If an exporter is configured, it will be used with a BatchSpanProcessor. If an exporter OR span processor is not configured programatically, this package will auto setup the default otlp
exporter with http/protobuf
protocol with a BatchSpanProcessor
.
spanLimits
Configure tracing parameters. These are the same trace parameters used to configure a tracer.
serviceName
Configure the service name.
Disable the SDK from the environment
Disable the SDK by setting the OTEL_SDK_DISABLED
environment variable to true
.
Configure log level from the environment
Set the log level by setting the OTEL_LOG_LEVEL
environment variable to enums:
NONE
,ERROR
,WARN
,INFO
,DEBUG
,VERBOSE
,ALL
.
The default level is INFO
.
Configure Trace Exporter from environment
This is an alternative to programmatically configuring an exporter or span processor. This package will auto setup the default otlp
exporter with http/protobuf
protocol if traceExporter
or spanProcessor
hasn't been passed into the NodeSDK
constructor.
Exporters
Environment variable | Description |
---|
OTEL_TRACES_EXPORTER | List of exporters to be used for tracing, separated by commas. Options include otlp , jaeger , zipkin , and none . Default is otlp . none means no autoconfigured exporter. |
OTLP Exporter
Environment variable | Description |
---|
OTEL_EXPORTER_OTLP_PROTOCOL | The transport protocol to use on OTLP trace, metric, and log requests. Options include grpc , http/protobuf , and http/json . Default is http/protobuf . |
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL | The transport protocol to use on OTLP trace requests. Options include grpc , http/protobuf , and http/json . Default is http/protobuf . |
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL | The transport protocol to use on OTLP metric requests. Options include grpc , http/protobuf , and http/json . Default is http/protobuf . |
Additionally, you can specify other applicable environment variables that apply to each exporter such as the following:
Useful links
License
Apache 2.0 - See LICENSE for more information.