---

Installation and usage

As Trace uses scoped packages, be sure to use npm version greater than 2.7.0.

npm install --save @risingstack/trace

If you can't update to [email protected] for whatever reason, you can still install Trace using npm i risingstack/trace-nodejs.

After you installed Trace as a dependency, you just require it at the beginning of your main file.

var trace = require('@risingstack/trace');

Configuration

You have to specify a reporter, which implements a send method to send the traced requests to the Trace servers or to your Logstash or any other storage.

If you choose to use our service, you need to specify an api key.

In case you want to use your Logstash, you have to add the connection informations.

You can specify these informations two ways. Either using a config file, or via environment variables. Currently we look for the config file at the project root by default, which you can override with an absolute path in the TRACE_CONFIG_PATH environment variable. We try to read the config file and if there are TRACE_APP_NAME and/or TRACE_REPORTER_TYPE with TRACE_REPORTER_CONFIG env, we override the configuration accordingly.

An example for the trace.config.js config file using the Trace servers:

/**
* The Trace configuration file
*/

var config = {};

config.appName = 'Users';

config.ignoreHeaders = {
  'user-agent': ['007']
};

config.reporter = require('@risingstack/trace/lib/reporters').trace.create({
 apiKey: '1234',
 appName: config.appName
});

module.exports = config;

Here please pay special attention to the ignoreHeaders option. With this, you can specify which requests should not be accounted. This can be extremely useful if you want to filter out the noise generated by your health checks for example.

An example for Logstash config:

/**
* The Trace configuration file
*/

var config = {};

config.appName = 'Users';

config.reporter = require('@risingstack/trace/lib/reporters').logstash.create({
  type: 'tcp',
  host: 'localhost',
  port: 12201
});

module.exports = config;

An example for how to start your app without a config file:

node TRACE_APP_NAME=MyApp TRACE_REPORTER_TYPE=trace TRACE_REPORTER_CONFIG='{\"apiKey\":1,\"appName\":\"MyApp\"}' index.js

Note that if you want to use your custom reporter, you have to use the config file: the TRACE_REPORTER_TYPE environment variable is either trace or logstash. Also, the TRACE_REPORTER_CONFIG variable should be a valid, parseable JSON string.

API

trace.report(Object)

This method can be use to report additional data to the Trace servers which later on helps with debugging.

trace.report({
  userId: 10
});

Returns an error if parameter is not an Object.

trace.getTransactionId()

This method can be use to get the current transactionId. It can be useful if you want to integrate trace with your current logging systems.

var transactionId = trace.getTransactionId();

Compatibility with Node versions

• node v0.10@latest
• node v0.12@latest
• iojs v2@latest
• iojs v3@latest
• node v4@latest

Supported HTTP Client libraries

• native HTTP/HTTPS clients
• request
• superagent
• more coming soon!