@risingstack/trace
Version:
RisingStack Trace Node.js collector
154 lines (108 loc) • 4.16 kB
Markdown
***
[](https://github.com/feross/standard)
[ ](https://codeship.com/projects/101987)
## 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.
```javascript
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.
```javascript
/**
* 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.
```javascript
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.
```javascript
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.
```javascript
var transactionId = trace.getTransactionId();
```
### trace.recordMetric(name, value)
This method can be used to record custom metrics values.
```javascript
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.
```javascript
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`.