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:

Remove the tracing library packages. See Remove the SignalFx Tracing Library for Node.js.
Deploy the Splunk Distribution of OpenTelemetry JS. See Deploy the Splunk Distribution of OpenTelemetry JS.
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.
Update the instrumentation entry point. See Update the instrumentation entry point
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:

Uninstall signalfx-tracing:
```
npm uninstall --save signalfx-tracing
```
If npm didn’t remove every dependency for signalfx-tracing, remove them manually.
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:

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
});

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.

Related Topics