ℹ️  SignalFx was acquired by Splunk in October 2019. See Splunk SignalFx for more information.

⚠️ Deprecation Notice

The SignalFx Tracing Library for Node.js is deprecated and will reach End of Support on June 8, 2023. After that date, this repository will be archived and no longer receive updates. Until then, only critical security fixes and bug fixes will be provided.

Consider using the Splunk Distribution of OpenTelemetry JS, which offers similar capabilities and fully supports the OpenTelemetry standard. To learn how to migrate, see Migrate from the SignalFx Node.js Tracing Library.

SignalFx Tracing Library for JavaScript

The SignalFx Tracing Library for JavaScript automatically instruments your Node.js application to capture and report distributed traces to SignalFx with an OpenTracing-compatible tracer.

The tracer has constant sampling (i.e., 100% chance of tracing) and reports every span. Where applicable, context propagation uses B3 headers.

For more information about configuring and using the agent, see the examples.

For advanced configuration information, see SignalFx Tracing Library for JavaScript - API.

Requirements and supported software

The library supports Node.js versions 4.7+, 6.9+, and 8+.

These are the supported libraries. Instrumentation for each library is in beta.

Library	Versions supported	Instrumentation name(s)	Notes
adonis	4+	use('adonis')
amqp10	3+	use('amqp10')
amqplib	0.5+	use('amqplib')
Bluebird	2+	use('bluebird')
Bunyan	1+	use('bunyan')
cassandra-driver	3+	use('cassandra-driver')
DNS	Supported Node	use('dns')
elasticsearch	10+	use('elasticsearch')
Express	4+	use('express')
GraphQL	0.10+	use('graphql')
hapi	2+	use('hapi')
http/https	Supported Node	use('http'), use('https')
ioredis	2+	use('ioredis')
Koa	2+	use('koa')
Knex	0.10+	use('bluebird'); use('knex')	Depends on bluebird instrumentation
Memcached	2.2+	use('memcached')
MongoDB-Core	2+	use('mongodb-core')
mysql	2+	use('mysql')
MySQL2	1+	use('mysql2')
Nest	4.x - 6.x	use('nest')
Net	Supported Node	use('net')
node-postgres	4+	use('pg')
Pino	2+	use('pino')
Q	1+	use('q')
Redis	0.12+	use('redis')
restify	3+	use('restify')
Sails	1+	use('sails')
Socket.IO	1.2+	use('socket.io')
when.js	3+	use('when')
winston	1+	use('winston')

Configure the SignalFx Tracing Library for JavaScript

Send traces from your Java application to a local or remote Smart Agent, OpenTelemetry Collector, or SignalFx ingest endpoint.

Configuration values

Configure these options as parameters for the init() method or as environment variables.

Config	Environment Variable	Default	Description
service	SIGNALFX_SERVICE_NAME	unnamed-nodejs-service	The service name to be used for this program.
url	SIGNALFX_ENDPOINT_URL	http://localhost:9080/v1/trace	The url of the Agent or Gateway to which the tracer will submit traces.
accessToken	SIGNALFX_ACCESS_TOKEN		The optional organization access token for trace submission requests
enabled	SIGNALFX_TRACING_ENABLED	true	Whether to enable the tracer.
debug	SIGNALFX_TRACING_DEBUG	false	Enable debug logging in the tracer.
tags	SIGNALFX_SPAN_TAGS	{}	Set global tags that should be applied to all spans. Format for the environment variable is key1:val1,key2:val2.
logInjection	SIGNALFX_LOGS_INJECTION	false	Enable automatic injection of trace IDs in logs for supported logging libraries.
logInjectionTags	SIGNALFX_LOGS_INJECTION_TAGS	['environment']	If log injection is on, these tags will be injected to log context.
flushInterval		2000	Interval in milliseconds at which the tracer will submit traces to the agent.
plugins		true	Whether or not to enable automatic instrumentation of external libraries using the built-in plugins.
	SIGNALFX_ENABLED_PLUGINS		A comma separated list of plugins that should be used. Only the plugins specified will be used and all other plugins will be ignore. All plugins will be used when no value is set.
recordedValueMaxLength	SIGNALFX_RECORDED_VALUE_MAX_LENGTH	1200	Maximum length an attribute value can have. Values longer than this limit are truncated. Any negative value turns off truncation.
enableServerTiming	SIGNALFX_SERVER_TIMING_CONTEXT	true	Enable injection of Server-Timing response header containing the current trace (e.g. Server-Timing: traceparent;desc="00-traceId-spanId-01").

Steps

To set up the library, install it and add the OpenTracing-compatible tracer to your application.

1. Install the latest release of the tracing library. You can install directly from npm or directly from the GitHub repository.

   npm:

     $ npm install signalfx-tracing

   GitHub:

     $ git clone https://github.com/signalfx/signalfx-nodejs-tracing.git
     $ npm install ./signalfx-nodejs-tracing

2. Set the service name for your application if not set via tracer configuration code:

     $ SIGNALFX_SERVICE_NAME=your_app_name node your_app.js

3. Configure the OpenTracing-compatible tracer to report traces to a Smart Agent or OpenTelemetry Collector. You have to include this before you import the target library.

   // init() invocation must occur before importing any traced library (e.g. Express)
   const tracer = require('signalfx-tracing').init({
     // Service name, also configurable via
     // SIGNALFX_SERVICE_NAME environment variable
     service: 'my-traced-service',
     // Smart Agent or Gateway endpoint, also configurable via
     // SIGNALFX_ENDPOINT_URL environment variable
     url: 'http://my_agent_or_gateway:9080/v1/trace', // http://localhost:9080/v1/trace by default
     // Optional organization access token, also configurable via
     // SIGNALFX_ACCESS_TOKEN environment variable
     accessToken: 'myOptionalOrganizationAccessToken',
     // Optional environment tag
     tags: {environment: 'myEnvironment'}
   })
   
   // auto-instrumented example Express application
   const express = require('express')
   const app = express()

Inject trace IDs in logs

Link individual log entries with trace IDs and span IDs associated with corresponding events. Inject trace context in logs with these loggers:

• Bunyan
• Pino
• Winston

You can also enable trace ID log injection with a custom logger.

When you configure trace ID log injection, your logger receives this info for the span.context:

signalfx: {
  trace_id: <trace_id>,
  span_id: <span_id>,
  service: <service name>,
  environment: <environment tag>
}

Inject trace information with Bunyan, Pino, or Winston

To transfer trace context (trace ID, span ID, service name, environment) to logs with Bunyan, Pino, or Winston, enable log injection with this environment variable:

$ SIGNALFX_LOGS_INJECTION=true

Inject additional span tags into log context

If log injection is enabled, in addition to trace ID and span ID, span tags can be injected to logs. To select which tags to inject, add logInjectionTags to init config, by default only environment is injected:

const tracer = require('signalfx-tracing').init({
  tags: {environment: 'production', region: 'eu'},
  logInjectionTags: ['environment', 'region']
})

After which your logger will receive:

signalfx: {
  trace_id: <trace_id>,
  span_id: <span_id>,
  service: <service name>
  environment: 'production',
  region: 'eu'
}

Or set the same injected tag via an environment var (with environment vars taking precendence):

$ SIGNALFX_LOGS_INJECTION_TAGS=environment,region

Inject trace IDs with a custom logger

To transfer trace context with a custom logger, add tracer.inject to your custom logger class like this:

const tracer = require('signalfx-tracing').init()
const formats = require('signalfx-tracing/ext/formats');

class Logger {
    log(level, message) {
        const span = tracer.scope().active();
        const time = new Date().toISOString();
        const record = { time, level, message };

        if (span) {
            // inject trace and span ID into `record` object
            tracer.inject(span.context(), formats.LOG, record);
        }

        console.log(JSON.stringify(record));
    }
}

module.exports = Logger;

where yourRecordObject is the object you want to inject span.context in.

License and versioning

The SignalFx Tracing Library for JavaScript is released under the terms of the BSD 3-Clause License. See the the license file for more details.

The SignalFx-Tracing Library for JavaScript is a fork of the DataDog APM JavaScript Tracer that has been modified to provide Zipkin v2 JSON formatting, B3 trace propagation functionality, and properly annotated trace data for handling by SignalFx Microservices APM.