Configure the Splunk Distribution of OTel JS for Splunk Observability Cloud

Configuration methods

To configure the Splunk Distribution of OpenTelemetry JS, you can use a combination of environment variables and arguments passed to the start() function:

• Environment variables

  For example: export OTEL_SERVICE_NAME='test-service'

• Arguments passed to the start() function

  For example: start({ serviceName: 'my-node-service', });

Configuration for each of the supported data type, such as metrics or tracing, is set using additional properties on the configuration object:

start({
   // general options like `serviceName` and `endpoint`
   metrics: {
      // configuration passed to metrics signal
   },
   profiling: {
      // configuration passed to profiling signal
   },
   tracing: {
      // configuration passed to tracing signal
   },
});

You can also activate the collection of a specific data type by passing a boolean value instead of an object. For example:

start({
   // general options like `serviceName` and `endpoint`
   metrics: true, // turn metrics on with default options
   profiling: true, // turn profiling on with default options
});

Resource configuration

Starting with version 4.0 of the Splunk Distribution of OpenTelemetry JS, manual resource creation using new Resource({}) is no longer supported.

To define custom resource attributes, use the resourceFromAttributes() helper from @opentelemetry/resources and merge it with the detected resource:

import { start } from '@splunk/otel';
import { resourceFromAttributes } from '@opentelemetry/resources';

start({
  resource: (detectedResource) => {
    return detectedResource.merge(resourceFromAttributes({
      'my.attribute': 'foo',
    }));
  },
});

This approach ensures compatibility with the latest OpenTelemetry SDK and allows you to define custom resource attributes programmatically.

General settings

The following settings are specific to the Splunk Distribution of OpenTelemetry JS:

Instrumentations configuration

The following settings control which instrumentations are activated:

For example, to turn off all default instrumentations and only turn on the bunyan instrumentation, set the following environment variables:

export OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED=false
export OTEL_INSTRUMENTATION_BUNYAN_ENABLED=true

The previous settings only apply to instrumentations loaded by the Splunk Distribution of OpenTelemetry JS by default. When using the programmatic API to supply a list of user-specified instrumentations, they have no effect.

Trace configuration

The following settings control tracing limits and attributes:

Samplers configuration

The following settings control trace sampling:

Exporters configuration

The following settings control trace exporters and their endpoints:

Jaeger exporter

To use the Jaeger exporter, add the @opentelemetry/exporter-jaeger package as in the following example:

const { start } = require('@splunk/otel');
const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
start({
   serviceName: 'my-node-service',
   tracing: {
      spanExporterFactory: (options) => {
      return new JaegerExporter({
         serviceName: options.serviceName,
         // Additional config
      })
      }
   },
});

Propagators configuration

The following settings control trace propagation:

For backward compatibility with the SignalFx Tracing Library for Node.js, use the b3multi trace propagator:

Linux

SHELLCopy

export OTEL_PROPAGATORS=b3multi

export OTEL_PROPAGATORS=b3multi

Windows PowerShell

SHELLCopy

$env:OTEL_PROPAGATORS=b3multi

$env:OTEL_PROPAGATORS=b3multi

Node.js settings for AlwaysOn Profiling

The following settings control the AlwaysOn Profiling feature for the Node.js agent:

To configure AlwaysOn Profiling programmatically, pass the arguments to the start function, as in the following example:

start({
   serviceName: '<service-name>',
   profiling: true,
   tracing: {
      // configuration passed to tracing signal
   },
});

Metrics configuration

The following settings activate runtime metrics collection:

Configuring an existing metrics client to send custom metrics

You can use an existing SignalFx client for sending custom metrics instead of creating and configuring a new one.

To configure an existing client, pass the following data to the start() function:

• signalfx: A JavaScript object with optional client and dimensions fields. The dimensions object adds a predefined dimension for each data point. The format for dimensions is {key: value, ...}.

The following is a list of dimensions added by default:

• service: See serviceName in Trace configuration.

• metric_source: splunk-otel-js

• node_version: process.versions.node, for example 16.10.0

Server trace information

To connect Real User Monitoring (RUM) requests from mobile and web applications with server trace data, activate Splunk trace response headers by setting the following environment variable:

Linux

SHELLCopy

export SPLUNK_TRACE_RESPONSE_HEADER_ENABLED=true

export SPLUNK_TRACE_RESPONSE_HEADER_ENABLED=true

Windows PowerShell

SHELLCopy

$env:SPLUNK_TRACE_RESPONSE_HEADER_ENABLED=true

$env:SPLUNK_TRACE_RESPONSE_HEADER_ENABLED=true

When you set this environment variable, your application instrumentation adds the following response headers to HTTP responses.

Access-Control-Expose-Headers: Server-Timing
Server-Timing: traceparent;desc="00-<serverTraceId>-<serverSpanId>-01"

The Server-Timing header contains the traceId and spanId in traceparent format. For more information, see the Server-Timing and traceparent documentation on the W3C website.