Skip to main content


This package provides tracing to front end of web applications for the collection of distributed tracing and performance metrics in Epsagon.



To install Epsagon, simply run:

npm install @epsagon/web


To initialize the tracer, import the SDK and call the init function before the start of your project.

import epsagon from "@epsagon/web";
epsagon.init({  token: "epsagon-token",  appName: "app-name-stage",});

Custom Tags#

To add additional information to spans there are two methods available. Batch add user identity information with the epsagon.identity function, or use the epsagon.tag function to add your own custom information.

Options for epsagon.identify include { userId, userName, userEmail, companyId, companyName }.

epsagon.identify({  userId: "7128f1a08a95e46c",  userName: "John Doe",  userEmail: "",  companyId: "fcffa7328813e4",  companyName: "Epsagon",});

Custom tags can only be added one at a time by passing a key and value to the tag function.

epsagon.tag("PurchaseId", "2ef5b4bfdd");


Advanced options can be configured as a parameter to the init() method.

tokenString-Epsagon account token
appNameStringEpsagon ApplicationApplication name that will be set for traces
collectorURLString-The address of the trace collector to send trace to
metadataOnlyBooleanfalseWhether to send only the metadata (true) or also the payloads (false)
propagateTraceHeaderUrlsArray*Which outgoing requests to add traceparent headers to. Defaults to all.
isEpsagonDisabledBooleanfalseA flag to completely disable Epsagon (can be used for tests or locally)

Trace Header Propagation#

By default all outgoing requests will be added with a traceparent header which allows Epsagon to connect the front end trace to the backend traces. Some external services will not accept a traceparent header on request. If you need to limit the traceparent headers to requests to internal services, pass in an array of the hosts you do want to connect to in the propagateTraceHeaderUrls param in the config.

import epsagon from "@epsagon/web";
epsagon.init({  token: "epsagon-token",  appName: "app-name-stage",  propagateTraceHeaderUrls: ["localhost", ""],});

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.