Docs » Supported integrations in Splunk Observability Cloud » Instrument back-end applications to send spans to Splunk APM » Instrument Node.js applications for Splunk Observability Cloud » Migrate from the SignalFx Tracing Library for Node.js

Migrate from the SignalFx Tracing Library for Node.js 🔗

The SignalFx Tracing Library for Node.js is deprecated and will reach End of Support on June 8th, 2023. Replace it with the Splunk Distribution of OpenTelemetry JS. Read the following instructions to learn how to migrate.

The Splunk Distribution of OpenTelemetry JS is based on the OpenTelemetry Instrumentation for Node.js, an open-source project that uses the OpenTelemetry API.

Compatibility and requirements 🔗

The Splunk Distribution of OpenTelemetry JS requires Node.js 14 and higher. See Splunk OTel JS compatibility and requirements.

See Considerations for migrating to Splunk Distribution of OpenTelemetry JS for considerations about migrating from the SignalFx Tracing Library for Node.js to the Splunk Distribution of OpenTelemetry JS.

Migrate to the Splunk Distribution of OpenTelemetry JS 🔗

To migrate from the SignalFx Tracing Library for Node.js to the Splunk Distribution of OpenTelemetry JS, follow these steps:

  1. Remove the tracing library packages. See Remove the SignalFx Tracing Library for Node.js.

  2. Deploy the Splunk Distribution of OpenTelemetry JS. See Deploy the Splunk Distribution of OpenTelemetry JS.

  3. Install the instrumentation packages for your library or framework, as instructed in Install and activate the Node.js instrumentation. For a list of supported instrumentation packages, see Default Instrumentation Packages on GitHub.

  4. Update the instrumentation entry point. See Update the instrumentation entry point

  5. Migrate your existing configuration. See Migrate settings.

Note

Semantic conventions for span names and attributes change when you migrate. For more information, see Migrate from SignalFx Smart Agent to the Splunk Distribution of OpenTelemetry Collector.

Remove the SignalFx Tracing Library for Node.js 🔗

Follow these steps to remove the tracing library and its dependencies:

  1. Uninstall signalfx-tracing:

    npm uninstall --save signalfx-tracing

  2. If npm didn’t remove every dependency for signalfx-tracing, remove them manually.

  3. Remove any additional instrumentation packages related to the SignalFx Tracing Library for Node.js.

Deploy the Splunk Distribution of OpenTelemetry JS 🔗

To install the Splunk Distribution of OpenTelemetry JS, see Instrument your Node.js application for Splunk Observability Cloud.

Update the instrumentation entry point 🔗

In your code, the instrumentation entry point for SignalFx tracing is similar to:

const tracer = require('signalfx-tracing').init({
 // your options here
})

You have two options to update your instrumentation entry point:

  1. Update the entry point to use @splunk/otel and start(), as shown in the following code:

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

start({
 // your new options here
});

  1. Automatically update your application to use Splunk Distribution of OpenTelemetry JS instead of SignalFx Tracing Library. To do so, run Node.js using the following command:

node -r @splunk/otel/instrument <your-app.js>

Note

To export traces directly to Splunk Observability Cloud, see Send data directly to Splunk Observability Cloud.

Migrate settings 🔗

To migrate settings from the SignalFx tracing library to the Splunk Distribution of OpenTelemetry JS, rename the following environment variables:

SignalFx environment variable

OpenTelemetry environment variable

SIGNALFX_ACCESS_TOKEN

SPLUNK_ACCESS_TOKEN

SIGNALFX_SERVICE_NAME

OTEL_SERVICE_NAME

SIGNALFX_ENDPOINT_URL

See Update the endpoint URL.

SIGNALFX_RECORDED_VALUE_MAX_LENGTH

OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT

SIGNALFX_TRACING_DEBUG

See Migrate debug log settings.

SIGNALFX_SPAN_TAGS

OTEL_RESOURCE_ATTRIBUTES as comma-separated key-value pairs. See Configure the Splunk Distribution of OTel JS for Splunk Observability Cloud.

SIGNALFX_LOGS_INJECTION

Not applicable. Log injection is always activated. See Connect Node.js trace data with logs for Splunk Observability Cloud.

SIGNALFX_LOGS_INJECTION_TAGS

Not applicable See Connect Node.js trace data with logs for Splunk Observability Cloud.

SIGNALFX_ENABLED_PLUGINS

Not applicable. To install instrumentation packages, see Add custom instrumentation.

SIGNALFX_SERVER_TIMING_CONTEXT

SPLUNK_TRACE_RESPONSE_HEADER_ENABLED

SIGNALFX_TRACING_ENABLED

OTEL_TRACE_ENABLED

If you’re using the passing configuration options as arguments to start(), update them as well:

SignalFx property

OpenTelemetry property

service

serviceName

url

endpoint

accessToken

accessToken

enabled

No equivalent. Use the OTEL_TRACE_ENABLED environment variable.

debug

No equivalent. See Migrate debug log settings.

tags

tracerConfig.resource

logInjection

logInjectionEnabled

logInjectionTags

No equivalent. Use tracerConfig.resource instead.

flushInterval

No equivalent. Set the OTEL_BSP_SCHEDULE_DELAY environment variable instead.

plugins

Not applicable. To install instrumentation packages, see Add custom instrumentation.

recordedValueMaxLength

Not applicable. Set the OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT environment variable instead.

enableServerTiming

serverTimingEnabled

Migrate debug log settings 🔗

To configure the debug logs produced by the instrumentation, the closest equivalent to SIGNALFX_TRACING_DEBUG is OTEL_LOG_LEVEL. See Activate diagnostic logging.

Update the endpoint URL 🔗

By default, the Splunk Distribution of OpenTelemetry JS uses the OTLP exporter instead of Jaeger.

If the receiver endpoint you were using with the SignalFx Tracing Library supports OTLP, set OTEL_EXPORTER_OTLP_ENDPOINT instead of SIGNALFX_ENDPOINT_URL. The OTel Collector supports OTLP.

Migrate custom metric collection 🔗

To migrate your custom metric instrumentation from the SignalFx client library, see Migrate from SignalFx metrics for Node.js.`

Migrate instrumentations 🔗

All libraries supported by the SignalFx Tracing Library for Node.js are support by the Splunk Distribution of OpenTelemetry JS. The only exceptions are listed in Considerations for migrating to Splunk Distribution of OpenTelemetry JS.

To find equivalent instrumentation, search for each instrumentation in the OpenTelemetry registry. If an instrumentation is not bundled, you can use custom instrumentation packages. See Add custom instrumentation.

Considerations for migrating to Splunk Distribution of OpenTelemetry JS 🔗

The following limitations apply when migrating from the SignalFx Tracing Library for Node.js:

  • The set of Node.js versions that Splunk Distribution of OpenTelemetry JS supports is different from the set that SignalFx Tracing Library supports. See :ref:nodejs-otel-requirements.

  • The default flush interval, which defines how frequently captured telemetry data is sent to the back end, is now 500 milliseconds instead of 2 seconds, and can’t be modified.

  • Autoinstrumentation is not available for the following libraries:

    • AdonisJS

    • amqp10

    • mongodb-core

    • sails

  • Some instrumentations have specific requirements:

    • express, koa, and hapi instrumentations require active http or https instrumentation to produce spans.

    • bluebird, q, and when are supported through AsyncLocalStorageContextManager (or AsyncHooksContextManager when the Node.js version is lower than 14.8).

Use the OpenTelemetry Registry to find autoinstrumentation packages for libraries supported by the Splunk Distribution of OpenTelemetry JS.

This page was last updated on Nov 10, 2023.