# Native Observability Cache Observer

## Overview

**Native Observability Cache Observer** extends the Native Observability ecosystem with a cache-focused diagnostic layer
for Drupal 11.

The module observes three important areas of runtime cache behavior:

- Drupal response cache headers such as `X-Drupal-Cache` and `X-Drupal-Dynamic-Cache`
- response cacheability metadata (cache tags, cache contexts, max-age)
- cache tag invalidations triggered during the request lifecycle

This makes it easier to understand whether a route is cache-friendly, which cache tags are attached to a response, and
when broad invalidations are happening.

This data also contributes to the broader technical snapshot surfaced in the
dashboard and long-form report.

---

## What the module captures

### Response cache layers

When Drupal exposes cache headers, the module records:

- page cache status
- dynamic page cache status
- request path and route name
- Native Observability request id when available

### Response cacheability metadata

For cacheable responses, the module records:

- cache tags count
- cache contexts count
- max-age
- full normalized metadata payload for inspection

### Cache tag invalidations

When Drupal invalidates cache tags, the module records:

- invalidated tag list
- invalidated tag count
- request correlation data when a request is active

---

## Administration UI

The module adds:

- a **Cache Observer** report under **Administration → Reports**
- a dedicated settings form under **Administration → Configuration → Development**

The report provides:

- cache hit/miss counters
- invalidation counters
- recent observed events table
- direct visibility into cache headers and cacheability metadata

---

## Cleanup integration

Cache Observer integrates with the central Native Observability cleanup manager.

This means:

- automatic cleanup works during cron when Native Observability cleanup is enabled
- manual cleanup actions also delete retained cache observer events
- force cleanup removes every stored cache observer record

---

## Status

Functional submodule ready for Drupal 11 Native Observability environments.
