Epsagon Documentation

Welcome to the Epsagon Documentation. You'll find comprehensive guides and documentation to help you start working with our product as quickly as possible. Let's jump right in!

Get Started

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 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 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-frameworks');

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.

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

FrameworkSupported VersionEpsagon LibraryAuto-tracing Supported
AWS LambdaAllepsagonYes, through the dashboard
Step FunctionsAllepsagonNo
OpenWhisk ActionAllepsagonNo
AWS BatchAllepsagonNo
GenericAllepsagonNo
Express>=3.0.0epsagon-frameworksYes
Hapi>=17.0.0epsagon-frameworksYes
Koa>=1.1.0epsagon-frameworksYes
KafkaJS>=1.2.0epsagon-frameworks<Yes
PubSub>=1.1.0epsagon-frameworksYes
SQS Consumer>=4.0.0epsagon-frameworksYes
amqplib>=0.5.0epsagon-frameworksYes
bunnybus>=7.0.0epsagon-frameworksYes
NATS>=1.4.0epsagon-frameworksYes
WS (Websocket)>=7.3.1epsagon-frameworksYes

Integrations

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

LibrarySupported Version
httpFully supported
httpsFully supported
http2Fully supported
dnsFully supported
aws-sdk>=2.2.0
amazon-dax-client>=1.0.2
@google-cloud>=2.0.0
@google-cloud/pubsub>=1.1.0
mysql>=2
mysql2>=1
pg>=4
mongodb>=2.2.12
kafkajs>=1.2.0
amqplib>=0.5.0
redis>=0.12.1
ioredis>=4.0.0
mqtt>=2.13.1
nats>=1.4.0
openwhisk>=3.0.0
ldapjs>=2.1.0
ws>==7.3.1

Configuration

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

ParameterEnvironment VariableTypeDefaultDescription
tokenEPSAGON_TOKENString-Epsagon account token
appNameEPSAGON_APP_NAMEStringApplicationApplication name that will be set for traces
metadataOnlyEPSAGON_METADATABooleantrueWhether to send only the metadata (true) or also the payloads (false)
useSSLEPSAGON_SSLBooleantrueWhether to send the traces over HTTPS SSL or not
traceCollectorURL-String-The address of the trace collector to send trace to
isEpsagonDisabledDISABLE_EPSAGONBooleanfalseA flag to completely disable Epsagon (can be used for tests or locally)
ignoredKeysEPSAGON_IGNORED_KEYSArray-Array of keys names (can be string or regex) to be removed from the trace
urlPatternsToIgnoreEPSAGON_URLS_TO_IGNOREArray[]Array of URL patterns to ignore the calls
sendTimeoutEPSAGON_SEND_TIMEOUT_SECFloat0.2The timeout duration in seconds to send the traces to the trace collector
decodeHTTPEPSAGON_DECODE_HTTPBooleantrueWhether to decode and decompress HTTP responses into the payload
httpErrorStatusCodeEPSAGON_HTTP_ERR_CODEInteger400The minimum number of an HTTP response status code to treat as an error
-DISABLE_EPSAGON_PATCHBooleanfalseDisable the library patching (instrumentation)
-EPSAGON_DEBUGBooleanfalseEnable debug prints for troubleshooting
-EPSAGON_PROPAGATE_NATS_IDBooleanfalseWhether to propagate a correlation ID in NATS.io calls for distributed tracing
-EPSAGON_ADD_NODE_PATHString-List of folders to looks for node_modules when patching libraries. Separated by :
-EPSAGON_DNS_INSTRUMENTATIONBooleanfalseWhether to capture dns calls into the trace
-EPSAGON_STEPS_IDString-The Epsagon step id from the ECS step functions state input
-EPSAGON_STEPS_NUMString0The step number of the ECS step functions state
-EPSAGON_DISABLE_HTTP_TRACE_IDBooleanfalseWhether to disable the trace ID propagation over HTTP calls

Updated a day ago


Node.js


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.