Distributed Tracing

Distributed tracing is a method used to monitor and observe requests as they travel through various services in a distributed system. It provides insights into the performance and behavior of applications by tracking the flow of requests across different components.

Whenever you have a problem using our APIs, we will ask you to enable distributed tracing and provide us with the traceparent-value. This will help us troubleshoot any issues you may encounter.

There are two headers that affect distributed tracing, that you should include in your API requests to us:

• traceparent (mandatory)
• tracestate (optional)

traceparent

Traceparent contains information about the trace context, including the trace ID and parent ID. The format is:

traceparent: 00-<trace-id>-<parent-id>-<flags>

In many cases your application will automatically create and set this header for you, but if you are using a custom HTTP client or library, you may need to set it manually.

The value generated should look like this, where the first part is 2 characters, then 32 characters, then 16 characters and finally 2 characters. Any other format is not valid. The formal definition of the format is as follows:

Regex pattern: ^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$

Example: 00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-00

If you need to generate it manually, you can use the following code snippet in C#:

static string GenerateTraceparent()
{
    // Default is W3C-format, but please verify that it corresponds to the format described above
    return new System.Diagnostics.Activity("CallToEG").Start().Id; 
}

Or in PHP:

function generateTraceparent()
{
    $traceId = bin2hex(random_bytes(16)); // Generate a random trace ID
    $parentId = bin2hex(random_bytes(8)); // Generate a random parent ID
    $flags = '00';
    return sprintf('00-%s-%s-%s', $traceId, $parentId, $flags);
}

tracestate

The tracestate header is an optional header to provide additional context about the trace. It can contain vendor-specific information and is typically used to propagate trace state across different systems. The format of the tracestate header is:

tracestate: <key1>=<value1>,<key2>=<value2>,...

In many cases your application will automatically create and set this header for you, but if you are using a custom HTTP client or library, you may need to set it manually.

See more details here: https://w3c.github.io/trace-context/