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');
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
Framework | Supported Version | Epsagon Library | Auto-tracing Supported |
---|---|---|---|
AWS Lambda | All | epsagon | Yes, through the dashboard |
Step Functions | All | epsagon | No |
OpenWhisk Action | All | epsagon | No |
AWS Batch | All | epsagon | No |
Generic | All | epsagon | No |
Express | >=3.0.0 | epsagon-frameworks | Yes |
Hapi | >=17.0.0 | epsagon-frameworks | Yes |
Koa | >=1.1.0 | epsagon-frameworks | Yes |
KafkaJS | >=1.2.0 | epsagon-frameworks | <Yes |
PubSub | >=1.1.0 | epsagon-frameworks | Yes |
SQS Consumer | >=4.0.0 | epsagon-frameworks | Yes |
amqplib | >=0.5.0 | epsagon-frameworks | Yes |
bunnybus | >=7.0.0 | epsagon-frameworks | Yes |
NATS | >=1.4.0 | epsagon-frameworks | Yes |
WS (Websocket) | >=7.3.1 | epsagon-frameworks | Yes |
Integrations
Epsagon provides out-of-the-box instrumentation (tracing) for many popular frameworks and libraries.
Library | Supported Version |
---|---|
http | Fully supported |
https | Fully supported |
http2 | Fully supported |
dns | Fully 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.
Parameter | Environment Variable | Type | Default | Description |
---|---|---|---|---|
token | EPSAGON_TOKEN | String | - | Epsagon account token |
appName | EPSAGON_APP_NAME | String | Application | Application name that will be set for traces |
metadataOnly | EPSAGON_METADATA | Boolean | true | Whether to send only the metadata (true ) or also the payloads (false ) |
useSSL | EPSAGON_SSL | Boolean | true | Whether to send the traces over HTTPS SSL or not |
traceCollectorURL | - | String | - | The address of the trace collector to send trace to |
isEpsagonDisabled | DISABLE_EPSAGON | Boolean | false | A flag to completely disable Epsagon (can be used for tests or locally) |
ignoredKeys | EPSAGON_IGNORED_KEYS | Array | - | Array of keys names (can be string or regex) to be removed from the trace |
urlPatternsToIgnore | EPSAGON_URLS_TO_IGNORE | Array | [] | Array of URL patterns to ignore the calls |
sendTimeout | EPSAGON_SEND_TIMEOUT_SEC | Float | 0.2 | The timeout duration in seconds to send the traces to the trace collector |
decodeHTTP | EPSAGON_DECODE_HTTP | Boolean | true | Whether to decode and decompress HTTP responses into the payload |
httpErrorStatusCode | EPSAGON_HTTP_ERR_CODE | Integer | 400 | The minimum number of an HTTP response status code to treat as an error |
- | DISABLE_EPSAGON_PATCH | Boolean | false | Disable the library patching (instrumentation) |
- | EPSAGON_DEBUG | Boolean | false | Enable debug prints for troubleshooting |
- | EPSAGON_PROPAGATE_NATS_ID | Boolean | false | Whether to propagate a correlation ID in NATS.io calls for distributed tracing |
- | EPSAGON_ADD_NODE_PATH | String | - | List of folders to looks for node_modules when patching libraries. Separated by : |
- | EPSAGON_AUTO_ADD_NODE_PATHS | Boolean | false | Auto add node_modules sub folders to look when patching libraries. |
- | EPSAGON_DNS_INSTRUMENTATION | Boolean | false | Whether to capture dns calls into the trace |
- | EPSAGON_STEPS_ID | String | - | The Epsagon step id from the ECS step functions state input |
- | EPSAGON_STEPS_NUM | String | 0 | The step number of the ECS step functions state |
- | EPSAGON_DISABLE_HTTP_TRACE_ID | Boolean | false | Whether to disable the trace ID propagation over HTTP calls |
Updated 3 days ago