What is Advanced Request Tracing in Cosmo Router?

Advanced Request Tracing (ART) returns the full execution plan and per-fetch detail of a federated GraphQL query inside the response under extensions.trace. It shows fetch types (parallel, serial, entity, batch), the actual subgraph requests, input/output data, and timing.

How do I activate ART for a request?

Send the request with the X-WG-Trace header set to true, or include wg_trace=true as a query parameter. ART is enabled by default in the router; you do not need a redeploy.

Does ART add overhead to normal traffic?

No. ART is only active when explicitly requested via the header or query parameter. There is no overhead on requests without it.

Can I run ART against production safely?

Yes, through the secure mechanism that requires a control plane connection. Production debugging is available on Cosmo Router 0.42.3 and later. ART never exposes data to unauthorized users.

Can I limit what the trace contains?

Yes. Configurable exclusions drop planner statistics, raw input, rendered input, output, or load statistics from the trace when you only need part of the picture.

Advanced Request Tracing for Federated GraphQL | Cosmo by WunderGraph

Q: Where does the trace appear?

Inside extensions.trace in the GraphQL response. The Cosmo Playground renders it visually so you can navigate the plan, fetch order, and timing without parsing JSON by hand.

The problem

Federated query execution is hidden by default

You see the response. You do not see the plan that produced it, the fetches that ran, or the order they ran in.

Federated execution is a black box

A single GraphQL query may produce many subgraph fetches in a planned order. Without visibility into the plan, optimization and debugging become guesswork.

Slow queries hide their bottlenecks

Aggregate latency tells you the query is slow. It does not tell you whether five serial fetches could have been one parallel step.

Production behavior diverges from staging

When a query works in staging and fails in production, you need the actual execution plan from production traffic, not a copy of what staging did.

Our solution

Execution plans, returned in the response

Activate ART per request and the trace ships back inside extensions.trace. The Cosmo Playground renders the plan visually so you can see the structure at a glance.

What ART captures

A client sends a query with the X-WG-Trace header (or the wg_trace query parameter).
The router executes normally and captures the execution plan structure in detail.
Every fetch is recorded with its type: parallel, serial, entity, or batch.
Actual subgraph requests, input data, and output data are attached to each fetch.
Per-step timing covers planning and each load operation.
The trace is returned in the GraphQL response under extensions.trace and renders in the Cosmo Playground.

No code changes. Per-request header. Zero overhead on normal traffic.

Advanced Request Tracing

Before & After

Before Cosmo	With Cosmo
Federated execution is opaque without subgraph fetch detail	extensions.trace shows every fetch, input, output, and timing
Slow queries with no per-fetch breakdown	Parallel vs serial fetches and subgraph latency in one response
Production debugging requires reproducing in staging	Secure ART against production with control plane auth (0.42.3+)
Always-on tracing overhead on every request	ART activates only via X-WG-Trace or wg_trace, with zero cost otherwise

Fetch types

Parallel, serial, entity, batch

Every fetch in the plan is labeled by type. See where the router parallelizes, serializes for dependencies, resolves entities by key, and batches operations.

Secure production ART requires a control plane connection (Cosmo Router 0.42.3+).

How Advanced Request Tracing works

01

Per-request header. Zero overhead otherwise.

Activate

Send the X-WG-Trace header or pass wg_trace=true as a query parameter. ART is enabled by default and can be turned off with ENGINE_ENABLE_REQUEST_TRACING=false.

02

Plan + fetches + input + output.

Capture

The router records the execution plan structure with every fetch type (parallel, serial, entity, batch) and the actual subgraph requests it sends.

03

extensions.trace, rendered in Playground.

Inspect

The trace is returned under extensions.trace in the GraphQL response. The Cosmo Playground renders it visually so you can navigate the plan without parsing JSON by hand.

04

Exclude planner, input, output, or load stats.

Control

Configurable exclusions drop planner stats, raw input, rendered input, output, or load stats from the trace when you do not need them.

Telemetry controls

Production, exclusions, and Studio

Secure production ART, configurable capture limits, and Playground visualization.

Header

Send X-WG-Trace: true with the request. Works for any HTTP client.

Query parameter

Add ?wg_trace=true to the request URL when you cannot set custom headers.

Production access

Secure production debugging requires a control plane connection. Cosmo Router 0.42.3 and later. Studio integration handles authentication.

Local debug mode

Set DEV_MODE=true for local debugging. Turn ART off entirely with ENGINE_ENABLE_REQUEST_TRACING=false.

Debug federated queries with ART

Send X-WG-Trace on a request and inspect the full execution plan in extensions.trace.

Start Free Read the Docs

See exactly how the router resolves any federated query