Epsagon Tracing for Node.js

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

Contents

• Installation
• Usage
  • Auto-tracing
  • Calling the SDK
  • Tagging Traces
  • Custom Errors
  • Filter Sensitive Data
  • Ignore Endpoints
• Frameworks
• Integrations
• Configuration
• Getting Help
• Opening Issues
• License

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

AWS Lambda

Tracing Lambda functions can be done in three methods:

1. Auto-tracing through the Epsagon dashboard.
2. Using the serverless-plugin-epsagon if you're using The Serverless Framework.
3. Calling the SDK.

Make sure to choose just one of the methods

Calling the SDK is simple:

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

// Wrap your entry point
module.exports.handler = epsagon.lambdaWrapper((event, context, callback) => {
  // Your code is here
});

// Async functions example
module.exports.handler = epsagon.lambdaWrapper(async (event) => {
  // Your code is here
});

Step Functions

Tracing Step Functions is similar to regular Lambda functions, but the wrapper changes from lambdaWrapper to stepLambdaWrapper:

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

// Wrap your entry point
module.exports.handler = epsagon.stepLambdaWrapper((event, context, callback) => {
  // Your code is here
});

// Async functions example
module.exports.handler = epsagon.stepLambdaWrapper(async (event) => {
  // Your code is here
});

ECS Step - You should pass Epsagon step_dict id from ECS state input into EPSAGON_STEPS_ID environment variables of the container, EPSAGON_STEPS_NUM is the step number of the ECS (default: 0). check the configuration section.

OpenWhisk Action

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 code is here
}

module.exports.main = epsagon.openWhiskWrapper(
  main,
  {
    token_param: 'epsagon-token', // name of the action parameter to take the token from
    appName: 'app-name-stage',
    metadataOnly: false
  }
);

AWS Batch

Tracing batch jobs running in AWS Batch can be done by wrapping the main handler/entrypoint of the code:

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


function process(params) {
  // Your code is here
}

const wrappedProcess = epsagon.wrapBatchJob(process);

Express

Tracing Express application can be done in two methods:

1. Auto-tracing using the environment variable.
2. Calling the SDK.

Calling the SDK is simple, and should be done in your main js file where the application is being initialized:

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

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

Tagging traces or setting custom errors can be by:

app.get('/', (req, res) => {
  req.epsagon.label('key', 'value');
  req.epsagon.setError(Error('My custom error'));
}

Hapi

Tracing Hapi application can be done in two methods:

1. Auto-tracing using the environment variable.
2. Calling the SDK.

Calling the SDK is simple, and should be done in your main js file where the application is being initialized:

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

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

Tagging traces or setting custom errors can be by:

server.route({
  method: 'GET',
  path:'/',
  handler: (request, h) => {
      request.epsagon.label('key', 'value');
      request.epsagon.setError(Error('My custom error'));
  }
});

Koa

Tracing Koa application can be done in two methods:

1. Auto-tracing using the environment variable.
2. Calling the SDK.

Calling the SDK is simple, and should be done in your main js file where the application is being initialized:

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

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

Tagging traces or setting custom errors can be by:

app.use(async ctx => {
  ctx.epsagon.label('key', 'value');
  ctx.epsagon.setError(Error('My custom error'));
});

WS (Websocket)

Tracing ws consumers can be done in two methods:

1. Auto-tracing using the environment variable.
2. Calling the SDK.

Calling the SDK is simple, and should be done in your main js file where the consumer is being initialized:

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

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

Tagging traces or setting custom errors can be by:

socket.on('message', (message) => {
    message.epsagon.label('key', 'value');
    message.epsagon.setError(Error('My custom error'));
}) 

KafkaJS

Tracing kafkajs consumers can be done in two methods:

1. Auto-tracing using the environment variable.
2. Calling the SDK.

Calling the SDK is simple, and should be done in your main js file where the consumer is being initialized:

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

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

Tagging traces or setting custom errors can be by:

await consumer.run({
  eachMessage: async ({ topic, partition, message }) => {
    message.epsagon.label('key', 'value');
    message.epsagon.setError(Error('My custom error'));
  },
})

PubSub

Tracing @google-cloud/pubsub consumers can be done in two methods:

1. Auto-tracing using the environment variable.
2. Calling the SDK.

Calling the SDK is simple, and should be done in your main js file where the consumer is being initialized:

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

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

Tagging traces or setting custom errors can be by:

await consumer.run({
  eachMessage: async ({ topic, partition, message }) => {
    message.epsagon.label('key', 'value');
    message.epsagon.setError(Error('My custom error'));
  },
})

SQS Consumer

Tracing sqs-consumer consumers can be done in two methods:

1. Auto-tracing using the environment variable.
2. Calling the SDK.

Calling the SDK is simple, and should be done in your main js file where the consumer is being initialized:

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

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

Tagging traces or setting custom errors can be by:

const messageHandler = message => {
  message.epsagon.label('key', 'value');
  message.epsagon.setError(Error('My custom error'));
};

amqplib

Tracing amqplib consumers can be done in two methods:

1. Auto-tracing using the environment variable.
2. Calling the SDK.

Calling the SDK is simple, and should be done in your main js file where the consumer is being initialized:

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

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

Tagging traces or setting custom errors can be by:

ch.consume(q, function cons(msg) {
  if (msg !== null) {
    msg.epsagon.label('key', 'value');
    msg.epsagon.setError(Error('My custom error'));
    ch.ack(msg);
  }
});

bunnybus

Tracing bunnybus consumers can be done in two methods:

1. Auto-tracing using the environment variable.
2. Calling the SDK.

Calling the SDK is simple, and should be done in your main js file where the consumer is being initialized:

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

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

Tagging traces or setting custom errors can be by:

// epsagon is added as an argument to the handler
handler: async ({message, metaData, ack, rej, requeue, epsagon}) => {
    epsagon.label('key', 'value');
    epsagon.setError(Error('My custom error'));
    await ack();
}

NATS

Tracing nats consumers can be done in two methods:

1. Auto-tracing using the environment variable.
2. Calling the SDK.

Calling the SDK is simple, and should be done in your main js file where the consumer is being initialized:

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

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

Generic

For any tracing, you can simply use the generic Epsagon wrapper using the following example:

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


function main(params) {
  // Your code is here
}

const wrappedMain = epsagon.nodeWrapper(main);

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.

Getting Help

If you have any issue around using the library or the product, please don't hesitate to:

• Use the documentation.
• Use the help widget inside the product.
• Open an issue in GitHub.

Opening Issues

If you encounter a bug with the Epsagon library for Node.js, we want to hear about it.

When opening a new issue, please provide as much information about the environment:

• Library version, Node.js runtime version, dependencies, etc.
• Snippet of the usage.
• A reproducible example can really help.

The GitHub issues are intended for bug reports and feature requests. For help and questions about Epsagon, use the help widget inside the product.

License

Provided under the MIT license. See LICENSE for details.

Copyright 2020, Epsagon