> ## Documentation Index
> Fetch the complete documentation index at: https://cosmo-docs.wundergraph.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitor the Response Cache

> Attributes, metrics, logs and queries for the hit rate, the store decision and the health of the cache.

> [!WARNING]
>
> **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:

```yaml config.yaml theme={"system"}
engine:
  debug:
    enable_cache_response_headers: true
```

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](https://cosmo-docs.wundergraph.com/router/advanced-request-tracing-art.md). 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:

```
INFO  Response cache enabled  {"fallback_ttl": "30s", "subgraph_overrides": 0, "storage_provider": "redis", "key_prefix": "cosmo_response_cache:", "storage_provider_id": "response_cache"}
```

`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:

```
WARN  Response cache degraded, serving from the subgraph instead
```

A request sent with [`only-if-cached`](https://cosmo-docs.wundergraph.com/router/response-cache/how-it-works#request-directives) 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](#cache-health), 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.

| Value | Meaning |
| - | - |
| `hit` | Answered from the cache. Nothing was sent to the subgraph. |
| `partial_hit` | Part of a merged entity fetch was answered from the cache and the rest was sent. Only merged entity fetches report it (`engine.enable_multi_fetch`, on by default). |
| `miss` | The cache was asked and could not answer. The fetch was sent to the subgraph. A batch with some entities cached is a `miss`. |
| `not_cacheable` | The cache was not asked: it is off for the subgraph, the fetch is not one it stores, such as a mutation, or the request sent `no-cache, no-store`. |

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:

```promql theme={"system"}
sum by (wg_subgraph_name) (rate(router_http_requests_total{wg_response_cache_status="hit"}[5m]))
/
sum by (wg_subgraph_name) (rate(router_http_requests_total{wg_response_cache_status=~"hit|partial_hit|miss"}[5m]))
```

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.

```promql theme={"system"}
sum by (wg_subgraph_name, wg_response_cache_status) (
  rate(router_http_request_duration_milliseconds_sum{wg_response_cache_status!=""}[5m])
)
/
sum by (wg_subgraph_name, wg_response_cache_status) (
  rate(router_http_request_duration_milliseconds_count{wg_response_cache_status!=""}[5m])
)
```

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:

```yaml config.yaml theme={"system"}
telemetry:
  metrics:
    attributes:
      - key: 'wg.operation.name'
        value_from:
          context_field: operation_name
```

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:

| Attribute | Meaning |
| - | - |
| `wg.entity.type` | The type the fetch resolves: the entity type, or `Query` for a root fetch. The types of a merged fetch are joined with a comma. |
| `wg.response_cache.store_decision` | What happened to the response of a fetch that was sent. |
| `wg.response_cache.lookup_duration_ms` | Time spent reading the cache. Not part of the fetch duration. |

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](https://cosmo-docs.wundergraph.com/router/response-cache/how-it-works.md#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.

| Value | Meaning |
| - | - |
| `hit` | Every fetch was answered from the cache. No subgraph was contacted. |
| `partial_hit` | At least one fetch was answered from the cache, in whole or in part. |
| `miss` | No fetch was answered from the cache. |

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:

```promql theme={"system"}
sum(rate(router_http_requests_total{wg_operation_response_cache_status="hit"}[5m]))
/
sum(rate(router_http_requests_total{wg_operation_response_cache_status!=""}[5m]))
```

The router request duration includes the time spent in the cache. It is the figure to compare a hit and a miss by:

```promql theme={"system"}
sum by (wg_operation_response_cache_status) (
  rate(router_http_request_duration_milliseconds_sum{wg_operation_response_cache_status!=""}[5m])
)
/
sum by (wg_operation_response_cache_status) (
  rate(router_http_request_duration_milliseconds_count{wg_operation_response_cache_status!=""}[5m])
)
```

## Expressions and access logs

[Template expressions](https://cosmo-docs.wundergraph.com/router/configuration/template-expressions.md) expose the same values:

* `response.cache.status` for the response.
* `subgraph.response.cache.status`, `storeDecision`, `lookupDuration` and `entityType` for a fetch.

```yaml config.yaml theme={"system"}
access_logs:
  router:
    fields:
      - key: 'cache_status'
        value_from:
          expression: 'response.cache.status'
```

## 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](https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring.md#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](#per-fetch) for that.

Failed calls by operation and cause. `canceled` is a client that went away, not a failing store:

```promql theme={"system"}
sum by (wg_response_cache_operation, wg_error_type) (
  rate(router_response_cache_operations_total{wg_error_type!="", wg_error_type!="canceled"}[5m])
)
```

Entries that were not written:

```promql theme={"system"}
sum(rate(router_response_cache_keys_total{wg_response_cache_operation="write", wg_response_cache_result="failed"}[5m]))
```

Cost of the cache per call. Writes are synchronous, so their duration adds to the response time:

```promql theme={"system"}
histogram_quantile(0.95,
  sum by (wg_response_cache_operation, le) (
    rate(router_response_cache_operation_duration_seconds_bucket[5m])
  )
)
```

Churn, as entries written per entry served. A value near or above one means entries are replaced about as often as they are used:

```promql theme={"system"}
sum(rate(router_response_cache_keys_total{wg_response_cache_operation="write", wg_response_cache_result="stored"}[5m]))
/
sum(rate(router_response_cache_keys_total{wg_response_cache_operation="lookup", wg_response_cache_result="found"}[5m]))
```

Lifetimes entries are written with:

```promql theme={"system"}
histogram_quantile(0.5, sum by (le) (rate(router_response_cache_write_ttl_seconds_bucket[15m])))
```

### 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:

```promql theme={"system"}
topk(10,
  sum by (wg_subgraph_name, wg_entity_type, wg_response_cache_store_decision) (
    rate(router_response_cache_fetches_total{wg_response_cache_status="miss"}[15m])
  )
)
```

Entity types of gRPC subgraphs and router plugins always appear here with `no_directive`. They are not supported by the cache. See [Limitations](https://cosmo-docs.wundergraph.com/router/response-cache/limitations.md#grpc-subgraphs-and-plugins-are-not-supported).

### Evictions

Redis evicts under its `maxmemory` policy, and the router does not see it. Read it from Redis, for example with [redis\_exporter](https://github.com/oliver006/redis_exporter):

```promql theme={"system"}
rate(redis_evicted_keys_total[5m])
rate(redis_expired_keys_total[5m])
redis_memory_used_bytes / (redis_memory_max_bytes > 0)
```

The last query needs a `maxmemory`. These count the whole Redis instance, including other data on it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.