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.
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/otelpackage:
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/instrumentCLI 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.
In order to send traces directly to Splunk Observability Cloud, you need to:
- Set
OTEL_TRACES_EXPORTERto"jaeger-thrift-splunk"to use the Jaeger exporter. - Set
OTEL_EXPORTER_JAEGER_ENDPOINTtohttps://ingest.<realm>.signalfx.com/v2/tracewhererealmis your Splunk APM realm (for example,https://ingest.us0.signalfx.com/v2/trace). - Set the
SPLUNK_ACCESS_TOKENto your Splunk Observability Cloud access token.
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.jsThen you can automatically instrument your application by running
node -r @splunk/otel/instrument index.jsThe 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.
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 scriptstartTracing() accept an optional Options argument. It can be used to customize many aspects of the tracing pipeline. For example:
startTracing({
serviceName: 'my-node-service',
});
startTracingis destructive to Open Telemetry API globals. Any globals set before runningstartTracingare overwritten.
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-winstonopentelemetry-instrumentation-elasticsearchopentelemetry-instrumentation-kafkajsopentelemetry-instrumentation-mongooseopentelemetry-instrumentation-sequelizeopentelemetry-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.
For troubleshooting issues with the Splunk Distribution of OpenTelemetry JS, see Troubleshooting.
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.