Splunk Distribution of OpenTelemetry for Node.js

Documentation for the current stable version (1.x) can be viewed here.

To access version 1.x examples and developer documentation, see /tree/1.x.

The Splunk Distribution of OpenTelemetry JS automatically instruments your Node application to capture and report distributed traces to Splunk APM.

This Splunk distribution comes with the following defaults:

W3C tracecontext and baggage propagation.
OTLP exporter configured to send spans to a locally running OpenTelemetry Collector over gRPC (default endpoint: localhost:4317).
Unlimited default limits for configuration options to support full-fidelity traces.

If you're currently using the SignalFx Tracing Library for Node and want to migrate to the Splunk Distribution of OpenTelemetry Node, see Migrate from the SignalFx Tracing Library for JS.

Get started

The following instructions assume that you're sending data to Splunk Observability Cloud using the OpenTelemetry Collector running on localhost. If you're running a different setup, refer to the configuration options to customize your settings.

Install the @splunk/otel package:

npm install @splunk/otel --save

Install the instrumentation packages for your library or framework:

npm install @opentelemetry/instrumentation-http --save

You can find a list of instrumentation packages supported out of the box here.

To install packages in addition to the default ones, see Plugins.

Run node app with the -r @splunk/otel/instrument CLI argument

export OTEL_SERVICE_NAME=my-node-svc
node -r @splunk/otel/instrument app.js

That's it - the telemetry data is now sent to the locally running Opentelemetry Collector. You can also instrument your app programmatically as described here.

Note: If you are using npm 6 or older, it'll warn you about missing peer dependencies. All of these dependencies are instrumentation packages and are completely optional. You can install the ones you need and ignore the rest. npm 7+ supports optional peer dependencies feature and will not complain about this.

Send data directly to Splunk Observability Cloud

In order to send traces directly to Splunk Observability Cloud, you need to:

Set OTEL_TRACES_EXPORTER to "jaeger-thrift-splunk" to use the Jaeger exporter.
Set OTEL_EXPORTER_JAEGER_ENDPOINT to https://ingest.<realm>.signalfx.com/v2/trace where realm is your Splunk APM realm (for example, https://ingest.us0.signalfx.com/v2/trace).
Set the SPLUNK_ACCESS_TOKEN to your Splunk Observability Cloud access token.

Automatically instrument an application

You can use the -r CLI flag to preload the instrumentation module and automatically instrument your Node.js application. For example, if you normally started your application as follows:

node index.js

Then you can automatically instrument your application by running

node -r @splunk/otel/instrument index.js

Correlate traces and logs

The Splunk Distribution of OpenTelemetry JS automatically injects trace metadata into logs so that Node.js logging libraries can access it. You can use trace metadata to correlate traces with log events and explore logs in Observability Cloud.

For more information, see Correlating traces with logs.

Manually instrument an application

You can also manually instrument your application by adding the following lines before everything else in your application.

const { startTracing } = require('@splunk/otel');

startTracing();

// rest of your application entry point script

startTracing() accept an optional Options argument. It can be used to customize many aspects of the tracing pipeline. For example:

startTracing({
  serviceName: 'my-node-service',
});

startTracing is destructive to Open Telemetry API globals. Any globals set before running startTracing are overwritten.

Default Instrumentation Packages

By default the following instrumentations will automatically be enabled if installed. In order to use any of these instrumentations, you'll need to install them with npm and then run your app with -r @splunk/otel/instrument flag as described above.

@opentelemetry/instrumentation-amqplib
@opentelemetry/instrumentation-aws-lambda
@opentelemetry/instrumentation-aws-sdk
@opentelemetry/instrumentation-bunyan
@opentelemetry/instrumentation-cassandra-driver
@opentelemetry/instrumentation-connect
@opentelemetry/instrumentation-dns
@opentelemetry/instrumentation-express
@opentelemetry/instrumentation-fastify
@opentelemetry/instrumentation-fs
@opentelemetry/instrumentation-generic-pool
@opentelemetry/instrumentation-graphql
@opentelemetry/instrumentation-grpc
@opentelemetry/instrumentation-hapi
@opentelemetry/instrumentation-http
@opentelemetry/instrumentation-ioredis
@opentelemetry/instrumentation-knex
@opentelemetry/instrumentation-koa
@opentelemetry/instrumentation-memcached
@opentelemetry/instrumentation-mongodb
@opentelemetry/instrumentation-mysql
@opentelemetry/instrumentation-mysql2
@opentelemetry/instrumentation-nestjs-core
@opentelemetry/instrumentation-net
@opentelemetry/instrumentation-pg
@opentelemetry/instrumentation-pino
@opentelemetry/instrumentation-redis
@opentelemetry/instrumentation-restify
@opentelemetry/instrumentation-tedious
@opentelemetry/instrumentation-winston
opentelemetry-instrumentation-elasticsearch
opentelemetry-instrumentation-kafkajs
opentelemetry-instrumentation-mongoose
opentelemetry-instrumentation-sequelize
opentelemetry-instrumentation-typeorm

You can find more instrumentation packages over at the OpenTelemetry Registry and enable them manually as described above.

Note that many of the instrumentation libraries offered by OpenTelemetry are still experimental.

Troubleshooting

For troubleshooting issues with the Splunk Distribution of OpenTelemetry JS, see Troubleshooting.

License

The Splunk distribution of OpenTelemetry JS Instrumentation is a distribution of the OpenTelemetry JS project. It is released under the terms of the Apache Software License version 2.0. See the license file for more details.

ℹ️ SignalFx was acquired by Splunk in October 2019. See Splunk SignalFx for more information.

rauno56/splunk-otel-js