@getcircuit/server-tracing NPM

`@getcircuit/server-tracing`

Tracing

This package provides a common interface for Circuit backend services to setup and use Tracing.

Setting up

!IMPORTANT The setup should be among the first things done on the service entrypoint.
More importantly it should be done before setting up any other package whenever possible, so that it can properly instrument any calls.
This is because may of the instrumentation libraries intercept imports to do the instrumentation.

Before using any tracing functionality you need to setup the tracing SDK to instrument all the packages needed.

To setup tracing, just call the provided setupTracing function and provide the necessary parameters (check the function docstring and signature for more information on how to use it).

Tearing down

Although not strictly necessary, this library provides the stopTracing function which can be awaited before shutting down a server.

This is useful for a graceful-shutdown situation on which we want to ensure that all the traces are sent to the collector before shutting down.

Helpers

Brief description on the exported helpers by this package

The `Tracing` class:

This utility can be used for a myriad of tracing operations, like creating new spans, and adding attributes to the current span.

Check the docstrings for full functionality.

The `isTracingEnvironment` function:

This is a useful function to ensure that the environment name used to set up tracing is a supported one.

Why is this necessary? Because we send the traces to different environments based on the nodeEnv value, and if we use an invalid value that environment might not exist.

The setupTracing function will error out if passed an environment that is not valid by isTracingEnvironment.

Ensuring a trace is sampled

This library has a functionality that bypasses any head-based or tail-based sampling configurations and ensures a trace is sampled.

To use this simply send a header called x-getcircuit-debug-id with any value along with a request. You can then search for the spans with the attribute circuit.debug.id equal to the value you sent in the header to find this request.