What is distributed tracing in a federated GraphQL graph?

Distributed tracing follows a single GraphQL request as it passes from the client through the Cosmo Router and into every subgraph it calls. Each request gets a unique trace ID and every step becomes a span, so you can see the full execution path of one request in one place.

How is the trace ID propagated to subgraphs?

The Cosmo Router propagates trace context using W3C Trace Context headers by default. Jaeger, B3, and Baggage propagation are available as options for compatibility with existing tracing stacks.

Does Distributed Tracing in Cosmo require code changes?

No. The Cosmo Router instruments traces automatically. Subgraphs only need to propagate the incoming trace context if you want subgraph-side spans correlated with the router span.

Where do I view the traces?

In Cosmo Studio. The Studio renders the full span tree for a request, including per-subgraph timing, span attributes, and error details. The view auto-refreshes every 10 seconds.

Can I send traces to my existing observability stack?

Yes. The router can export traces to Cosmo Cloud and to any OpenTelemetry-compatible backend at the same time, so existing APM, Jaeger, or Datadog setups keep working alongside Cosmo Studio.

Is Distributed Tracing available on the free plan?

Distributed Tracing in Cosmo Studio is available on Pro and Enterprise plans. OpenTelemetry export from the Cosmo Router itself is available on Free, Pro, and Enterprise.

How do I get the trace ID back to a client?

The router can return the request trace ID in the response headers. The setting is configurable. Clients can include it in error reports so support teams can pull the trace from Studio immediately.

Distributed Tracing for Federated GraphQL | Cosmo by WunderGraph

The problem

Federated requests vanish into a maze of subgraph logs

A single GraphQL operation can touch many services. Without a shared trace, debugging means crawling through every service one log at a time.

Logs scattered across subgraphs are not a debugger

When a federated query fails, log lines exist in every subgraph. Without a shared trace ID, correlating them by timestamp is guesswork that costs hours per incident.

You cannot fix latency you cannot localize

Slow page loads on a product catalog point to a subgraph, but which one? Without per-subgraph timing, optimization becomes trial and error.

New deployments hide subtle regressions

A subgraph rollout looks healthy at the metric level and still pushes p95 latency up. Without trace-level comparison, the regression hides until users complain.

Our solution

One trace per request, every span in Studio

The router captures spans for every phase of a federated request and stitches subgraph spans into the same trace. Cosmo Studio renders the result as a single timeline.

What happens for every request

A client request hits the router. The router creates spans for parsing, validation, planning, and execution.
Each subgraph request gets a trace ID propagated via W3C Trace Context (or Jaeger, B3, or Baggage).
Subgraph spans collected at the router are correlated with the request trace.
Span attributes carry GraphQL operation details. Errors include the response message, extension codes, and stack traces.
Cosmo Studio renders the full span tree with timing breakdowns and error highlights.
The Studio dashboard auto-refreshes every 10 seconds while you debug a live incident.

Open the trace, find the failure, ship the fix.

Distributed tracing

Before & After

Before Cosmo	With Cosmo
Logs scattered across subgraphs with no shared trace ID	One trace per request with spans for router and every subgraph
Slow federated queries with no way to localize latency	Studio timeline shows which subgraph span dominates duration
Subtle regressions after deploys are hard to spot	Inspect individual traces and replay queries from Studio
Separate tracing config per service	Router-native OTEL spans with W3C propagation by default

Existing APM

Works with your existing trace backend

Cosmo Router can export traces to Cosmo Cloud and to your existing OpenTelemetry-compatible backend at the same time. Subgraph teams continue using the APM they already run; the Studio view adds GraphQL context on top.

How Distributed Tracing works in Cosmo

01

Automatic span capture, no app code changes.

Capture

The router instruments every GraphQL operation. Spans cover parsing, validation, planning, and execution against each subgraph.

02

W3C Trace Context by default.

Propagate

Each subgraph request carries trace context. W3C Trace Context is the default; Jaeger, B3, and Baggage propagation are available as options.

03

Errors carry codes and stack traces.

Annotate

Span attributes carry operation name and type. Error spans capture the error message, GraphQL extension codes, and stack traces. GraphQL variables can be exported for query replay when tracing.export_graphql_variables is enabled.

04

Studio dashboard refreshes every 10 seconds.

Visualize

Cosmo Studio renders the full span tree with per-subgraph timing. The dashboard auto-refreshes every 10 seconds while you debug a live incident.

What you see in Studio

The span tree, the error, the timing

Per-subgraph timing

Every subgraph fetch is its own span. See exactly which service added latency, and how much.

Error context

Error spans capture the GraphQL error message, extension codes, and stack trace where available.

Query replay

When tracing.export_graphql_variables is enabled, variables are exported with the trace so you can replay the failing query in the Cosmo Playground.

Auto-refresh

The Studio dashboard refreshes every 10 seconds, so live incidents update as new traces arrive.

Trace federated GraphQL in Studio

Open a trace, find the failing subgraph span, and replay the query from Studio.

Start Free Read the Docs

Follow every federated GraphQL request from client to subgraph