Skip to content
This repository has been archived by the owner on Jun 13, 2023. It is now read-only.

Latest commit

 

History

History
150 lines (107 loc) · 5.78 KB

README.md

File metadata and controls

150 lines (107 loc) · 5.78 KB
Raw


Note: This repository is archived since Epsagon is no longer supported

Epsagon Tracing for Web

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

Contents

Installation

To install Epsagon, simply run:

npm install @epsagon/web --save

Usage

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',
})

Import and install as webpack bundle

<script type="text/javascript" src="<Bundle URL path"></script>
<script>
  Epsagon.default.init({
    token: 'epsagon-token',
    appName: 'app-name-stage',
  })
</script>

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: '[email protected]',
  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')

Configuration

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

Parameter Type Default Description
token String - Epsagon account token
appName String Epsagon Application Application name that will be set for traces
collectorURL String - The address of the trace collector to send trace to
metadataOnly Boolean false Whether to send only the metadata (true) or also the payloads (false)
propagateTraceHeaderUrls Array * Which outgoing requests to add traceparent headers to. Defaults to all.
urlPatternsToIgnore Array [] Which outgoing requests to ignore (and not add traceparent to. Default to []
networkSamplingRatio Float 1.0 How many spans are exported, configured between 0.0 (send nothing) to 1.0 (send everything)
maxQueueSize Integer 2048 Maximum queue size (bytes), afterwhich spans are dropped
scheduledDelayMillis Integer 5000 Delay interval in milliseconds between two consecutive exports
exportTimeoutMillis Integer 30000 How many milliseconds the export can run before it is cancelled
maxBatchSize Integer 1024 Maximum batch size (bytes) of every export. Has to be small or equal to maxQueueSize
isEpsagonDisabled Boolean false A flag to completely disable Epsagon (can be used for tests or locally)
epsagonDebug Boolean false Enable debug prints for troubleshooting. Note: if this flag is true, this will override the logLevel
logLevel String INFO The default Log level. Could be one of: DEBUG, INFO, WARN, ERROR, ALL.

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', 'sub.example.com'],
  urlPatternsToIgnore: [".*example.*", ".*abc.*"]  
})

FAQ

Question: I'm getting CORS errors in my application.

Answer: epsagon-browser adds traceparent HTTP header to all outgoing HTTP calls. You should make sure your backend accepts this header. If you are using 3rd party services, you can use propagateTraceHeaderUrls parameter to only add the header to your urls.

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, 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 2021, Epsagon