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 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'
]
}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();Compatibility with Node versions
- node v0.10@latest
- node v0.12@latest
- node v4@latest
- node v5@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.