Do I need to add any instrumentation code?

No. The router generates OpenTelemetry spans automatically for every request. The default router configuration enables telemetry. You only need to configure an export destination if you want to send traces to an external backend.

What does enginePlanCacheHit = false mean on repeated requests?

The query plan was computed fresh rather than served from cache. On the second and subsequent executions of the same operation, a cache miss can indicate: Advanced Request Tracing (ART) was enabled (which bypasses the cache), the cache is full and the plan was evicted, or multiple router instances each have cold caches.

How do I identify which subgraph is slow?

Expand the Operation - Execution span in the trace view. Each subgraph fetch appears as a child span with its own duration. The slowest child span identifies the subgraph adding latency.

What is Advanced Request Tracing (ART)?

ART provides additional per-field trace data for deep debugging. It is indicated by the `engineRequestTracingEnabled: true` attribute on the Planning span. ART adds overhead and is intended for debugging specific operations, not for production traffic.

Can I send traces to Jaeger or my existing observability stack?

Yes. The router exports traces via the standard OpenTelemetry protocol (OTLP) over HTTP or gRPC. You can send to Jaeger, Zipkin, a self-hosted OTEL Collector, or any backend that accepts OTLP.

Is Performance Debugging available on the free plan?

Yes. OpenTelemetry span generation is available on Free, Pro, and Enterprise plans. The Cosmo Studio trace viewer is included on all plans.

GraphQL Performance Debugging | Cosmo by WunderGraph

The problem

Slow GraphQL requests with no visibility into why

HTTP-level metrics tell you a request was slow. They do not tell you whether the delay was in planning, execution, or a specific subgraph.

Slow requests have no per-phase breakdown

Generic APM tools report total HTTP latency. They cannot tell you whether the delay came from query planning, a specific subgraph fetch, or authentication. Diagnosing the root cause requires guesswork.

You cannot tell if the query plan cache is working

If a query is slow on repeated calls, the cache may not be hitting. Without a cache hit signal in the trace, you cannot distinguish a cache miss from a slow subgraph.

Federation adds subgraph latency you cannot attribute

A query touching multiple subgraphs can be slow because of one service. Without per-subgraph span data, the slow service is invisible in aggregated metrics.

Our solution

Four spans, zero instrumentation code

The router automatically generates OpenTelemetry spans for every phase of every request. No custom code, no decorators, no middleware. The spans appear in Cosmo Studio and in any OTEL-compatible backend.

How per-phase tracing works

The router automatically generates OpenTelemetry spans for each phase of every GraphQL request. No custom instrumentation required.
The Authenticate span covers time spent validating against configured authentication providers. It appears only when authentication is enabled.
The Operation - Parse and Validate span covers parsing of variables and query body, and validation against the schema.
The Operation - Planning span covers construction of the optimized query plan, including normalization. The `enginePlanCacheHit` attribute shows whether the plan came from cache.
The Operation - Execution span covers fetching data from subgraphs and aggregating the response. Expand it to see individual subgraph fetch times.
View traces in Cosmo Studio or export to Jaeger, Zipkin, Datadog, Grafana Tempo, or any OTLP-compatible backend.

Automatic. No code changes required.

Performance Debugging

Before & After

Before Cosmo	With Cosmo
Total request latency only—no phase breakdown	Separate spans for parsing, planning, and execution
No visibility into whether query plans come from cache	`enginePlanCacheHit` attribute on every planning span
Subgraph latency invisible in aggregated metrics	Per-subgraph timing visible in the execution span
Performance investigation takes hours of guesswork	Bottleneck identified from trace view in minutes

Span reference

Four spans per request

Authenticate: Auth provider validation time. Appears only when a request goes through an authentication provider. An error indicates an unauthorized request.
Operation - Parse and Validate: Time spent parsing query body and variables, and validating against the schema.
Operation - Planning: Time spent constructing the optimized query plan, including normalization.
Operation - Execution: Time spent fetching from subgraphs and aggregating data. Expand to see per-subgraph timing.

How Performance Debugging works in Cosmo

01

Auth time isolated.

Authenticate

Optional span. Appears when a request goes through a configured authentication provider. Duration shows how long auth validation took. An error in this span means the request was unauthorized.

02

Parse + schema validation.

Parse & Validate

The first mandatory phase. Covers parsing the query body and variables, then validating the operation against the schema. Slow spans here point to schema complexity or malformed queries.

03

enginePlanCacheHit attribute.

Planning

Building the optimized query plan and normalizing the operation. The `enginePlanCacheHit` attribute is `true` if the plan came from cache. A `false` value on repeat calls means the cache is not hitting.

04

Per-subgraph timing.

Execution

Fetching data from subgraphs and aggregating the response. Expand this span to see individual subgraph fetch times. The slow subgraph is visible without guessing.

Capabilities

Studio, cache signals, and external export

Built-in viewer, cache hit attribute, ART detection, and OTEL export.

Cosmo Studio trace viewer

View traces with visual timelines and span hierarchies directly in Cosmo Studio. Filter by operation, time range, or latency threshold.

enginePlanCacheHit attribute

Set on every planning span. `true` means the plan came from cache. `false` on repeat executions means the plan is being recomputed—pointing to cache eviction or ART usage.

ART detection

The `engineRequestTracingEnabled` attribute indicates whether Advanced Request Tracing was active. ART adds overhead and should not be enabled for all production traffic.

External backend export

Spans export over HTTP or gRPC to any OTLP-compatible backend: Jaeger, Zipkin, Datadog, Grafana Tempo, or a self-hosted OTEL Collector.

Know exactly where your GraphQL is slow

Per-phase traces are on by default. Open Cosmo Studio and start debugging immediately.

Start Free Read the Docs

See which phase is slow before you guess.