Advanced Request Tracing (ART)

This section is about Advanced Request Tracing (ART) and how you can leverage it to debug execution plans and understand exactly how the Router resolves a request.

Enabling Advanced Request Tracing may pose a potential security risk. For this reason, we have implemented a mechanism to ensure secure communication from Cosmo Studio to your routers. This allows to debug routers in production 🎉

A connection with the controlplane is required and a router with version 0.42.3 or higher.

Advanced Request Tracing (ART) renders the Execution Plan including verbose information about how it was resolved as a JSON and adds it to the GraphQL response in the "extensions" part of the response using the "trace" key.

You get the following information from ART

• planning timings, e.g. how long it took to generate an execution plan

• the general structure of the execution plan

• the types of fetches (load operations) the Router does, like parallel, serial, entity, batch entity, etc.

• what actual requests are being sent to the Subgraphs

• what data was used to render the input for a load operation

• the rendered input of a load operation

• the output of a load operation

• the timings, like latency, of a load operation

All of this information can be quite useful to fully understand how the Router resolves a request and why it might be slow or behave unexpectedly.

Configuration

For convenience, Advanced Request Tracing is enabled by default. When starting the Router, a warning indicates if the feature is active.

To fully disable Advanced Request Tracing, set the following environment variable:

ENGINE_ENABLE_REQUEST_TRACING=false

Request Parameters

To use Advanced Request Tracing, you need to either use Request Headers or Query Parameters. To disable ART, simply omit the "X-WG-Trace" Header or the "wg_trace" Query Parameter.

Headers

You must set the following Header to enable tracing

X-WG-Trace=true

Query Parameter

It's also possible to use Query Parameters

POST http://example.com/graphql?wg_trace=true

Optional Arguments

Other (optional) arguments that are available:

• exclude_planner_stats (exclude planner timings in the trace)

• exclude_raw_input_data (exclude the raw input data for a loader)

• exclude_input (exclude the rendered input data for a loader)

• exclude_output (exclude the output of a loader)

• exclude_load_stats (exclude load stats like latency)

• enable_predictable_debug_timings (useful for debugging, makes timings constant)

Examples

Enable Advanced Tracing but exclude planner stats and input via Header

X-WG-Trace=exclude_planner_stats,exclude_input

Enable Advanced Tracing but exclude output via Query Parameters

POST http://example.com/graphql?wg_trace=exclude_output

Development

For security reasons, we don't enable Advanced Request Tracing (ART) by default but you can enable it by setting the router environment variable DEV_MODE to true and using the following header in the playground:

{
  "X-WG-TRACE" : "true"
}