Skip to content

Latest commit

 

History

History
164 lines (122 loc) · 8.88 KB

MIGRATING.md

File metadata and controls

164 lines (122 loc) · 8.88 KB

Migrate from the SignalFx Tracing Library for Node.js

The Splunk Distribution of OpenTelemetry for Node.js replaces the SignalFx Tracing Library for Node.js. If you’re using the SignalFx Tracing Library, migrate to the Splunk Distribution of OpenTelemetry for Node.js to send traces to Splunk Observability Cloud. The Splunk Distribution of OpenTelemetry for Node.js uses OpenTelemetry to instrument applications, which is an open-source API to gather telemetry data, and has a smaller footprint.

Because the SignalFx Tracing Library for Node.js uses OpenTracing and the Splunk Distribution of OpenTelemetry for Node.js uses OpenTelemetry, the semantic conventions for span names and attributes change when you migrate. For more information, see Migrate from OpenTracing to OpenTelemetry.

Getting help

If you experience any issues following the guide below, or something is unclear, or missing, don't hesitate to open an issue in GitHub. Any and all ideas for improvements are also welcome.

Known limitations as compared to SignalFx Tracing Library

Changes to defaults

  • Default flush interval, which defines how frequently captured telemetry data is sent to the backend, is now 30s instead of 2s

Requirements

This Splunk Distribution of OpenTelemetry requires Node.js 8.5 or higher, see more information here If you're still using an earlier version of Node.js, continue using the SignalFx Tracing Library for Node.js.

Current effective required Node.js version is: node-current

Migration steps

Instrumented libraries

With the exception of explicitly listed limitations we aim to support all libraries supported by signalfx-nodejs-tracing. To find an equivalent autoinstrumentation open https://opentelemetry.io/registry/ and for each instrumentation from signalfx-nodejs-tracing's README search by the name of the library in the registry.

For example, if you'd like to migrate instrumentation for mysql, go to https://opentelemetry.io/registry/?s=mysql&component=&language=js#.

Once you have identified an instrumentation package, install it using npm or yarn.

Environment variables

Rename environment variables:

OpenTracing environment variable OpenTelemetry environment variable notes
SIGNALFX_ACCESS_TOKEN SPLUNK_ACCESS_TOKEN
SIGNALFX_SERVICE_NAME OTEL_SERVICE_NAME
SIGNALFX_ENDPOINT_URL no direct equivalent See the notes on endpoint
SIGNALFX_RECORDED_VALUE_MAX_LENGTH OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT
SIGNALFX_TRACING_DEBUG no direct equivalent See Instrumentation logs
SIGNALFX_SPAN_TAGS OTEL_RESOURCE_ATTRIBUTES Format needs to be changed to key1=val1,key2=val2
SIGNALFX_LOGS_INJECTION n/a Logs injection is now enabled by default.
SIGNALFX_LOGS_INJECTION_TAGS n/a
SIGNALFX_ENABLED_PLUGINS n/a see the README section about instrumentations
SIGNALFX_SERVER_TIMING_CONTEXT SPLUNK_TRACE_RESPONSE_HEADER_ENABLED
SIGNALFX_TRACING_ENABLED n/a

Programmatic configuration

Update these programmatic configuration options (passed as arguments to startTracing()):

OpenTracing property OpenTelemetry property Notes
service serviceName
url endpoint
accessToken accessToken
enabled - no equivalent, but Environment Variable can be used
debug - no direct equivalent, see instrumentation logs
tags tracerConfig.resource
logInjection logInjectionEnabled
logInjectionTags - no direct equivalent, but tracerConfig.resource can be used
flushInterval - no direct equivalent, contact us if you had customized this value
plugins - see the README section about instrumentations
recordedValueMaxLength maxAttrLength
enableServerTiming serverTimingEnabled

Instrumentation entry point

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

becomes

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

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

and requires installing @splunk/otel first, using either npm or Yarn. Same as in signalfx-nodejs-tracing, this code is to be run before your import or require statements.

Alternatively, you can append the flag -r @splunk/otel/instrument instead when launching node (it runs startTracing under the hood). In that case you cannot use programmatic configuration and must rely on environment variables only.

Instrumentation logs

There isn't a one-to-one mapping for SIGNALFX_TRACING_DEBUG. The closest equivalent is OTEL_LOG_LEVEL, however the logged information will be different.

Note that this section is about the logs produced by instrumentation, and not about the logs produced by the application.

Logging level is controlled by the OTEL_LOG_LEVEL environment variable. The two most common values are:

  • INFO: the default value
  • VERBOSE: highest value likely to be needed

For all possible log levels see this source file.

There is no default output for logs. Even if you set OTEL_LOG_LEVEL=VERBOSE, nothing is output to the console. You need to set an output first, for example to stdout, by adding DiagConsoleLogger:

const { diag, DiagConsoleLogger, DiagLogLevel } = require('@opentelemetry/api');

diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ALL);

Endpoint

This package uses OTLP for export format by default so SIGNALFX_ENDPOINT_URL doesn't have an direct equivalent without replacing the exporter with one that uses Jaeger format. Options to consider:

  • Using OTLP: If the receiving endpoint supports OTLP over gRPC (for example, the OTel Collector), set OTEL_EXPORTER_OTLP_ENDPOINT instead of SIGNALFX_ENDPOINT_URL.
  • Replacing OTLP with Jaeger: To export directly to Splunk Observability Cloud, set the exporter back to Jaeger by:
    • setting the OTEL_TRACES_EXPORTER environment variable to jaeger-thrift-splunk and
    • using OTEL_EXPORTER_JAEGER_ENDPOINT to configure the endpoint instead of SIGNALFX_ENDPOINT_URL. See the example).