Debug header
For development, the router can report the cache result of each response in a header:config.yaml
X-WG-Response-Cache with HIT, PARTIAL_HIT or MISS. The header is sent on synchronous HTTP responses only, not on @defer responses or batched operations. Do not enable it in production.
For detail per fetch, use Advanced Request Tracing. The trace of each fetch shows its cache status, store decision, keys, entries found and written, the Cache-Control and Vary it was decided on, and any write error.
Logs
At startup, the router logs the cache settings:fallback_ttl is the value under all. subgraph_overrides counts the entries under subgraphs. When the invalidation endpoint is enabled, a second line reports its address and which indexes are on.
A failed read or write does not fail a request. The router serves from the subgraph and logs:
only-if-cached is the exception: a failed lookup fails its fetch.
The warning is sampled to one line per second. An unreachable store fails every cacheable fetch of every request, and unsampled logging would add to the outage. Every failure is counted in the cache health metrics, when they are enabled.
Per fetch
While the cache is enabled, every subgraph fetch carrieswg.response_cache.status on its metrics and its Engine - Fetch span.
A hit still counts as a subgraph request, with a latency close to zero. The attribute sits next to
wg.subgraph.name on router.http.requests, router.http.request.duration_milliseconds and router.http.requests.error.
Hit rate per subgraph, among the fetches the cache was asked about:
wg_response_cache_status!="" in the denominator to measure against every fetch.
Mean fetch duration by status. Compare means, not quantiles: the smallest Prometheus bucket is 10 ms, and every hit falls into it.
config.yaml
exclude_metric_labels under telemetry.metrics.prometheus or telemetry.metrics.otlp.
A hit sends no request, so it has no transport telemetry: no request or response size, no in-flight count, no connection metrics. Its subgraph access log line has no method, path, url or request header fields.
Store decision
TheEngine - Fetch span also carries:
The store decision explains why a type is never served from the cache. Its values are
stored, fetch_failed, uncacheable_status, invalid_response, response_errors, invalid_cache_control, no_store, no_cache, no_directive, no_lifetime, unusable_vary, private_without_id and no_entity. What is stored lists when each one applies.
A type that is stored on every miss and never hit has a lifetime too short for its traffic, or a key that never repeats.
The decision is absent for a fetch answered from the cache and for one that is not cacheable. A request sent with no-store reports it as absent instead of stored. The subgraph.response.cache.storeDecision expression reads empty for these. The decision is taken before the write, which can still fail.
Per response
The router request carrieswg.operation.response_cache.status on its metrics, its root span and its Operation - Execute span. It summarizes the fetches of one response.
A fetch that was not answered from the cache counts against a hit, whether it missed or was not cacheable. A response whose fetches were all not cacheable reports
miss.
The attribute is absent for mutations, subscriptions, WebSocket operations, introspection, requests that failed before execution, and requests deduplicated onto another in flight. The debug header is absent for the same requests.
Share of responses served entirely from the cache:
Expressions and access logs
Template expressions expose the same values:response.cache.statusfor the response.subgraph.response.cache.status,storeDecision,lookupDurationandentityTypefor a fetch.
config.yaml
Cache health
Metrics for the store itself are off by default. The metrics, their attributes and how to turn them on are listed under Response Cache Metrics. The queries below use them. A lookup asks for the shared key and, for a request with a private id, the private key too. Usually only one of the two is found. Keys counted asmissing are therefore no measure of the hit rate. Use the per-fetch status for that.
Failed calls by operation and cause. canceled is a client that went away, not a failing store:
Cache-hostile types
The types that miss most often, and why. A busy type can rank high even when most of its fetches hit, so compare with its hits:no_directive. They are not supported by the cache. See Limitations.
Evictions
Redis evicts under itsmaxmemory policy, and the router does not see it. Read it from Redis, for example with redis_exporter:
maxmemory. These count the whole Redis instance, including other data on it.