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.

export EPSAGON_TOKEN=<EPSAGON-TOKEN>
export EPSAGON_APP_NAME=<APP-NAME-STAGE>
export EPSAGON_METADATA=FALSE
export NODE_OPTIONS='-r epsagon-frameworks'

node <APP-NAME>

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

ENV EPSAGON_TOKEN=<EPSAGON-TOKEN>
ENV EPSAGON_APP_NAME=<APP-NAME-STAGE>
ENV EPSAGON_METADATA=FALSE
ENV NODE_OPTIONS='-r epsagon-frameworks'

CMD node <APP-NAME>

You can see the list of auto-tracing supported frameworks

Calling the SDK

Another simple alternative is to initialize the package within the code:

const epsagon = require('epsagon');

epsagon.init({
    token: <EPSAGON-TOKEN: string>,
    appName: <APP-NAME-STAGE: string>,
    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. These tags follow specific metrics in the form of key-value pairs.

Tags must be labeled in order to be followed. Simply label a key-value pair.

epsagon.label(<KEY>, <VALUE>)
epsagon.label('itemsInCart', itemsInCart)

Tags can also be labeled inside the init method, Dockerfile, or shell script.

epsagon.init({
    token: <EPSAGON-TOKEN: string>,
    appName: <APP-NAME-STAGE: string>,
    labels: [ [<KEY>, <VALUE>], ['userID', userID] ]
});

Valid types for tags 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.

try {
    /* exception thrown, ex:  */
    1 / 0;
} catch (err) {
    epsagon.setError(err);
}

/* or manually specify error */
epsagon.setError(Error('Custom Error Occured'));

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

Custom Warnings

This API allows you to flag the trace with a warning and also enables more flexible alerting.

try {
    /* exception thrown, ex:  */
    1 / 0;
} catch (err) {
    epsagon.setWarning(err);
}

/* or manually specify error */
epsagon.setWarning(Error('Custom Error Occured'));

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: string>,
    appName: <APP-NAME-STAGE: string>,
    ignoredKeys: ['password', /.*_token$/],
    urlPatternsToIgnore: ['example.com', 'stackoverflow.com'],
});

ignoredKeys property contains keys wished to be ignored.
urlPatternsToIgnore property is used to ignore outgoing HTTP/S calls to specific domains.

Both properties can contain strings, regular expressions, and predicate functions. Loose matches are performed on strings, so that First Name matches first_name.

Ignore Endpoints

Conversely, you can ignore incoming requests from specific endpoints

epsagon.ignoreEndpoints(['/healthcheck']);

Trace URL

You can get the Epsagon dashboard URL for the current trace, using the following:

# Inside some endpoint or function
console.log('Epsagon trace URL:', epsagon.getTraceUrl())

This can be useful to have an easy access the trace from different platforms.

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.