# trace-nodejs

**Repository Path**: mirrors_Financial-Times/trace-nodejs

## Basic Information

- **Project Name**: trace-nodejs
- **Description**: Trace is a visualised stack trace platform designed for microservices.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-09-24
- **Last Updated**: 2026-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

![Trace logo](https://cloud.githubusercontent.com/assets/1764512/8830445/83e8263c-309c-11e5-9f7f-aa3420e9b2f0.png)
***
[![js-standard-style](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard)
[ ![Codeship Status for RisingStack/trace-nodejs](https://codeship.com/projects/8322f860-3ac7-0133-8753-0e111daba52d/status?branch=master)](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']
  }
}
```

**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.**

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

## Compatibility with Node versions

* node v0.10@latest
* node v0.12@latest
* iojs v2@latest
* iojs v3@latest
* node v4@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`.