Nonviolent Pigeon Manifestation

    @splunk/otel
    TypeScript icon, indicating that this package has built-in type declarations

    0.18.0 • Public • Published

    Beta GitHub release (latest by date) Splunk GDI specification npm node-current Codecov GitHub branch checks state

    Splunk Distribution of OpenTelemetry for Node.js

    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:

    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.

    1. Install the @splunk/otel package:
    npm install @splunk/otel --save
    
    1. 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.

    1. 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:

    1. Set OTEL_TRACES_EXPORTER to "jaeger-thrift-splunk" to use the Jaeger exporter.
    2. 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).
    3. 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. We provide the stopTracing method, but it won't revert to OTel API globals set before startTracing was run, it will only disable globals, which startTracing set.

    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-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.

    Troubleshooting

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

    License and versioning

    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.

    Install

    npm i @splunk/otel

    DownloadsWeekly Downloads

    5,984

    Version

    0.18.0

    License

    Apache-2.0

    Unpacked Size

    6.31 MB

    Total Files

    115

    Last publish

    Collaborators

    • rhe
    • splunk-tli
    • stsui
    • splunker
    • dexa187
    • edsplunk
    • kova71
    • apruneda
    • danielsplunk
    • splunk_dashboard_publisher
    • codycoats_splunk
    • spuchbauer-splunk
    • splunk-observability-instrumentation