Docs » µAPM Instrumentation Guide » Node.js Instrumentation

Node.js Instrumentation 🔗

Important

Before you start instrumenting your applications, review the information in Instrumentation Overview.

Adding tracing functionality to your Node.js project, like in other platforms, generally consists of incorporating the initialization of a global tracer and using its interfaces for the creation and modification of spans to denote the runtime state of your application. For web applications implementing dozens of routes and using middleware that generates complex database queries, manual instrumentation can become burdensome. This is especially true for cross-team deployments, where service owners and instrumentors don’t share memberships, or when legacy components are currently without SMEs. Fortunately, there is a helpful library for auto-instrumenting your applications: SignalFx-Tracing for JavaScript.

$ npm install signalfx-tracing
const tracer = require('signalfx-tracing').init({
  // Optional Smart Agent or Gateway target.  Default is http://localhost:9080/v1/trace
  url: 'http://my_agent_or_gateway:9080/v1/trace'
});

With this tracer initialization, a number of libraries and frameworks will become automatically instrumented and report their activity to SignalFx in real time. To establish distributed traces over the remote request-response points of your application, we automatically configure the B3 span context propagation codec for HTTP clients and supported web frameworks.

const tracer = require('signalfx-tracing').init({
  url: 'http://my_agent_or_gateway:9080/v1/trace',
});

// Import an auto-instrumented Express
const express = require('express')
const myApp = express()

myApp.get('/myEndpoint', (req, res) => {
  // Access automatically generated span for additional instrumentation
  const span = tracer.scope().active()
  span.setTag('requestHeader', req.header('x-my-important-header'))
  myBusinessLogic(() => res.status(200).send('Processed!'))
})

Node.js versions 4.7+, 6.9+, and 8+ are supported. Currently the following libraries are provided with auto-instrumentation:

Library Supported Versions
AdonisJs 4+
amqp10 (Beta) 3+
amqplib (Beta) 0.5+
Bluebird 2+
Bunyan (Beta) 1+
DNS Supported Node Versions
elasticsearch 10+
Express 4+
GraphQL (Beta) 0.10+
hapi 2+
http/https Supported Node Versions
ioredis 2+
Koa 2+
Memcached (Beta) 2.2+
MongoDB-Core 2+
mysql 2+
MySQL2 1+
Net Supported Node Versions
node-postgres 4+
Pino (Beta) 2+
Q 1+
Redis 0.12+
restify (Beta) 3+
Sails 1+
Socket.IO 1.2+
when.js 3+
winston (Beta) 1+

For detailed, library-specific instrumentation instructions and examples, please see the utility’s documentation.