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');
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
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.
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.
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();
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.
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>
- node v0.10@latest
- node v0.12@latest
- node v4@latest
- node v5@latest
- node v6@latest
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
.