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/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.
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
tohttps://ingest.<realm>.signalfx.com/v2/trace
whererealm
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.
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
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.
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. We provide thestopTracing
method, but it won't revert to OTel API globals set beforestartTracing
was run, it will only disable globals, whichstartTracing
set.
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-bunyan
@opentelemetry/instrumentation-cassandra-driver
@opentelemetry/instrumentation-dns
@opentelemetry/instrumentation-express
@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-net
@opentelemetry/instrumentation-pg
@opentelemetry/instrumentation-pino
@opentelemetry/instrumentation-redis
@opentelemetry/instrumentation-restify
@opentelemetry/instrumentation-winston
opentelemetry-instrumentation-amqplib
opentelemetry-instrumentation-aws-sdk
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.
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.