jbpionnier/trace-nodejs

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 npm@2.7.0 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 can specify the configuration two ways. Configuration options can be set via environment variables or using a config module. We look for a config module named trace.config.js at your current working directory by default, which can be overridden with the TRACE_CONFIG_PATH environment variable. Having a config module is optional, but some options may be set only with it. In order to use our service, you need to specify an api key and and a service name at minimum. The corresponding environment variables are: TRACE_API_KEY and TRACE_SERVICE_NAME.

An example for how to start your app with environment variables:

node TRACE_SERVICE_NAME=MyApp TRACE_API_KEY=1 index.js

An example with a custom config file using the Trace servers:

node TRACE_CONFIG_PATH=/path/to/my/config.js index.js

or simply

node index.js

if it's in the current working directory.

/**
* Your Trace configuration file at /path/to/my/config.js
*/

module.exports = {
  serviceName: 'your-awesome-app',
  apiKey: 'KEEP_ME_SECRET',
  ignoreHeaders: {
    'user-agent': ['007']
  },
  ignorePaths: [
    '/healthcheck'
  ],
  ignoreStatusCodes: [
    401,
    404
  ],
  ignoreOutgoingHosts: [
    'google.com'
  ],
  disableInstrumentations: [
    'mongodb'
  ],
  proxy: 'http://168.63.76.32:3128'
}

Note: Custom reporters are no longer supported in trace 2.x

Note: If you are running your app with NODE_ENV=test, Trace won't start

API

trace.report(String, [Object])

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

trace.report('name', {
  userId: 10
});

Throws an error if first parameter is not a String. Throws an error if second parameter is not an Object.

trace.reportError(String, Error)

This method can be used to send errors to the Trace servers - note that transactions that use this method are not subject to sampling, so it will be collected all the time.

trace.reportError('mysql_error', new Error('connection refused'));

Throws an error if first parameter is not a String.

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

trace.recordMetric(name, value)

This method can be used to record custom metrics values.

trace.recordMetric('user/imageUpload', 6)

The name must have the following format: <Category>/<Name> The value must be a number.

trace.incrementMetric(name, [amount])

This method can be used to record increment-only type of metrics.

trace.incrementMetric('user/signup')

The name must have the following format: <Category>/<Name>

Compatibility with Node versions

node v0.10@latest
node v0.12@latest
node v4@latest
node v5@latest
node v6@latest

Migrating from 1.x to 2.x

The trace.config.js file changed, and has the following format:

module.exports = {
  serviceName: 'your-awesome-app',
  apiKey: 'KEEP_ME_SECRET'
}

Also, from 2.x you can specify these values using only environment variables: TRACE_SERVICE_NAME and TRACE_API_KEY.

jbpionnier / trace-nodejs