The Node.js tracing library allows you to collect and monitor your Node.js application traces, calls, metrics, and correlation to logs.

📘

Tracing Lambda functions

To trace AWS Lambda functions in Node.js please refer to the following AWS Lambda tracing.

Installation

Install our Node.js library using npm:

npm install epsagon-frameworks

Setup

To run the library as part of your application, you can choose between one of the following methods:

  1. Using auto-tracing.
  2. Calling the SDK.

Auto-tracing

Auto-tracing loads the Epsagon library as part of your application. Configurations can be done through the environment variables:

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.

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

CMD node <APP-NAME>

Calling the SDK

Another alternative is to copy the snippet into your code:

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

epsagon.init({
    token: <EPSAGON-TOKEN: string>,
    appName: <APP-NAME-STAGE: string>,
    metadataOnly: false,
});

The supported frameworks and libraries are listed here.

Verification

Now that you’ve completed the setup, you can see new traces coming up on your traces search screen. If you don't see any please refer to the FAQ section.

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_AUTO_ADD_NODE_PATHSBooleanfalseAuto add node_modules sub folders to look when patching libraries.
-EPSAGON_DNS_INSTRUMENTATIONBooleanfalseWhether to capture dns calls into the trace
-EPSAGON_LOGGING_TRACING_ENABLEDBooleantruewhether to add an Epsagon ID to the logs in order to correlate traces to logs in the dashboard

📘

Further reading

The tracing library is open source and available on GitHub. For more detailed configurations and features read about the tracing library.


What’s Next

Learn more about the tracing library

Did this page help you?