Skip to main content
Beta feature. Response caching is a feature that has been released in beta status.

Debug header

For development, the router can report the cache result of each response in a header:
config.yaml
Responses then carry 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:
A request sent with 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 carries wg.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:
Match 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.
A fetch’s duration starts after the lookup. The time spent in the cache is not part of it. To break the hit rate down by operation, add the operation name to metrics. It is on every span, but not on metrics unless the router exports to Cosmo Cloud:
config.yaml
The attribute is not attached while the cache is disabled. It can be dropped from metrics with 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

The Engine - 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 carries wg.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:
The router request duration includes the time spent in the cache. It is the figure to compare a hit and a miss by:

Expressions and access logs

Template expressions expose the same values:
  • response.cache.status for the response.
  • subgraph.response.cache.status, storeDecision, lookupDuration and entityType for 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 as missing 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:
Entries that were not written:
Cost of the cache per call. Writes are synchronous, so their duration adds to the response time:
Churn, as entries written per entry served. A value near or above one means entries are replaced about as often as they are used:
Lifetimes entries are written with:

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:
Entity types of gRPC subgraphs and router plugins always appear here with no_directive. They are not supported by the cache. See Limitations.

Evictions

Redis evicts under its maxmemory policy, and the router does not see it. Read it from Redis, for example with redis_exporter:
The last query needs a maxmemory. These count the whole Redis instance, including other data on it.