Skip to main content

Node.js

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.