Performance · Performance Debugging

See which phase is slow before you guess.

Cosmo Router generates OpenTelemetry spans for authentication, parsing, planning, and execution. The enginePlanCacheHit attribute shows whether a plan came from cache. View traces in Cosmo Studio or export to any OTEL backend.

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

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

Performance Debugging

Before & After

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

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 & 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

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

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

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.

FAQ

Performance Debugging on Cosmo Router

• Do I need to add any instrumentation code?
• What does enginePlanCacheHit = false mean on repeated requests?
• How do I identify which subgraph is slow?
• What is Advanced Request Tracing (ART)?
• Can I send traces to Jaeger or my existing observability stack?
• Is Performance Debugging available on the free plan?

Full details in the performance debugging documentation.