This package provides tracing to Node.js applications for the collection of distributed tracing and performance metrics in Epsagon.

📘

Open source repository

This is an open-source project which can be found at our GitHub repository.

Installation

To install Epsagon, simply run:

npm install epsagon

Usage

Auto-tracing

The simplest way to get started in some frameworks is to install epsagon-frameworks:

npm install epsagon-frameworks

epsagon-frameworks extends the base epsagon support to more frameworks.

And run your node command:

export EPSAGON_TOKEN=epsagon-token
export EPSAGON_APP_NAME=app-name-stage
export NODE_OPTIONS='-r epsagon-frameworks'
node command

For example:

export EPSAGON_TOKEN=your-token
export EPSAGON_APP_NAME=express-prod
export NODE_OPTIONS='-r epsagon-frameworks'
node app.js

When using inside a Dockerfile, you can use ENV instead of export.

You can see the list of auto-tracing supported frameworks

Calling the SDK

Another simple alternative is to copy the snippet into your code:

const epsagon = require('epsagon-frameworks');

epsagon.init({
  token: 'epsagon-token',
  appName: 'app-name-stage',
  metadataOnly: false,
});

To run on your framework please refer to supported frameworks

Tagging Traces

You can add custom tags to your traces, for easier filtering and aggregations.

Add the following call inside your code:

epsagon.label('key', 'value');
epsagon.label('userId', userId);

You can also use it to ship custom metrics:

epsagon.label('key', 'metric')
epsagon.label('itemsInCart', itemsInCart)

You can also use it iniside init function:

epsagon.init({
  token: 'epsagon-token',
  appName: 'app-name-stage',
  labels: [['key', 'value'], ['userId', userId]],
});

Valid types are string, boolean and number.

In some frameworks tagging can be done in different ways.

Custom Errors

You can set a trace as an error (although handled correctly) to get an alert or just follow it on the dashboard.

Add the following call inside your code:

try {
  // something bad happens
} catch (err) {
  epsagon.setError(err);
}

// Or manually specify Error object
epsagon.setError(Error('My custom error'));

In some frameworks custom errors can be declared in different ways.

Filter Sensitive Data

You can pass a list of sensitive properties and hostnames and they will be filtered out from the traces:

epsagon.init({
  token: 'epsagon-token',
  appName: 'app-name-stage',
  metadataOnly: false,
  ignoredKeys: ['password', /.*_token$/],
  urlPatternsToIgnore: ['example.com', 'auth.com'],
});

The ignoredKeys property can contain strings (will perform a loose match, so that First Name also matches first_name), regular expressions, and predicate functions.
Also, you can set urlPatternsToIgnore to ignore HTTP calls to specific domains.

Ignore Endpoints

You can ignore certain incoming requests by specifying endpoints:

epsagon.ignoreEndpoints(['/healthcheck'])

Frameworks

The following frameworks are supported by Epsagon.
Some require installing also epsagon-frameworks

Integrations

Epsagon provides out-of-the-box instrumentation (tracing) for many popular frameworks and libraries.

Configuration

Advanced options can be configured as a parameter to the init() method or as environment variables.