Epsagon Instrumentation for Node.js

This package provides an instrumentation to Node.js code running on functions for collection of distributed tracing and performance monitoring.

Installation

From your project directory:

npm install --save epsagon

Getting started (AWS Lambda)

Simply use the wrapper to send traces from your code:

const epsagon = require('epsagon');
epsagon.init({
    token: 'my-secret-token',
    appName: 'my-app-name',
    metadataOnly: false, // Optional, send more trace data
});

function handler(event, context, callback) {
    callback(null, 'It worked!')
}

handler = epsagon.lambdaWrapper(handler)

Getting started (Apache OpenWhisk)

You should pass the Epsagon token to your action as a default parameter, so that you don't have to expose important credentials in your code. The name of the parameter can be configured using token_param, in this example we use EPSAGON_TOKEN

const epsagon = require('epsagon');

function main(params) {
    // your main function
}

module.exports.main = epsagon.openWhiskWrapper(main, {
    token_param: 'EPSAGON_TOKEN', // name of the action parameter to take the token from
    appName: 'my-app-name',
    metadataOnly: false // Optional, send more trace data
});

You can then pass the EPSAGON_TOKEN as a default parameter into your action using the wsk command line client:

$ wsk action update <myaction> --parameter EPSAGON_TOKEN <your-epsagon-token>

Custom labels

You can add custom labels to your traces. Filters can later be used for filtering traces that contains specific labels:

function handler(event, context, callback) {
    epsagon.label('myCustomLabel', 'labelValue');
    callback(null, 'It worked!')
}

Custom errors

You can set a trace as an error (although handled correctly) by catching an error:

function handler(event, context, callback) {
    try {
        // something bad happens
    } catch (err) {
        epsagon.setError(err);
    }

    callback(null, 'It worked!')
}

Or manually specify Error object:

function handler(event, context, callback) {
    epsagon.setError(Error('My custom error'));
    callback(null, 'It worked!')
}

Filter sensitive data

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

epsagon.init({
    token: 'my-secret-token',
    appName: 'my-app-name',
    metadataOnly: false, // Optional, send more trace data
    ignoredKeys: ['password', /.*_token$/ , …],
    urlPatternsToIgnore: ['example.com', 'auth.com'],
});

The ignoredKeys property can contain strings (will perform a lose match, so that First Name also matches first_name), regular expressions, and predicate functions.

Alternatively you can pass a comma-separated list of sensitive keys using the EPSAGON_IGNORED_KEYS environment variable to get the same effect.

Also you can set urlPatternsToIgnore to ignore HTTP calls to specific domains, or set it through EPSAGON_URLS_TO_IGNORE as a comma separated string of hostnames.

Web frameworks

Support for Express, Hapi, and other frameworks is done through epsagon-frameworks

Optional instrumentations

An environment variable must be added to start tracing the following libraries:

dns: EPSAGON_DNS_INSTRUMENTATION = true

Copyright

Provided under the MIT license. See LICENSE for details.

Copyright 2019, Epsagon