Cache Explain

Cache Explain shows, on any page, whether each caching layer served it: browser, CDN (Cloudflare or Akamai), Varnish, and Drupal's page caches, and explains why it was a hit or a miss.

A Drupal page can be cached in up to six places between your visitor and the database. When a change doesn't appear, or a page is slower than it should be, it's hard to tell which layer is
responsible. Cache Explain adds a block that inspects the current page and shows the result for each layer in one panel, with plain-language explanations aimed at people who are still learning how Drupal caching works.

Features

• One panel, every layer. Each layer gets its own collapsible row with a HIT, MISS, WARN, INFO or N/A badge:
  • Browser cache: Cache-Control, Expires, ETag, Last-Modified.
  • CDN, Cloudflare: every CF-Cache-Status value explained, the CF-Ray and data centre, and where the edge TTL comes from
    (Cloudflare-CDN-Cache-Control, CDN-Cache-Control or s-maxage).
  • CDN, Akamai: sends Akamai's debug Pragma headers and reads X-Cache, X-Cache-Remote, X-Check-Cacheable and the
    cache keys.
  • Reverse proxy (Varnish or nginx): X-Varnish, X-Cache, X-Cache-Hits, Age, Via.
  • Internal Page Cache and Dynamic Page Cache (Drupal core): X-Drupal-Cache, X-Drupal-Dynamic-Cache, plus cache tags, contexts and max-age when Drupal sends them.
  • Render cache and cache bins: these never appear in HTTP headers, so Cache Explain explains what they do and how to inspect them.
• Explains, not just reports. Every layer says how it's detected, what a HIT and a MISS mean, and what each header tells you. For example, it flags pages whose Cache-Control allows CDN caching while Cloudflare isn't caching them because no Cache Rule makes HTML eligible.
• Knows how the layers stack. When the CDN answers from its own cache, the reverse-proxy row says "Not reached" instead of guessing from headers that belong to the CDN's stored copy.
• Reproducible. Shows the equivalent curl command, so you can run the same check from a terminal, and lists every raw response header.
• Looks the same under any theme. The panel renders inside a shadow root, so your theme's CSS can't change its layout and its CSS can't leak into your theme.

When to use it:

• A content change isn't showing up, and you need to know which cache is holding the old copy.
• You're putting a CDN or Varnish in front of Drupal and want to confirm pages are actually cached at the edge.
• You're learning Drupal caching and want to see the layers react as you change settings.
• You're reviewing a site's performance setup or handing it over to another team.

Post-Installation

There is no configuration page. Cache Explain provides a single block.

1. Enable the module: drush en cache_explain, or use Extend.
2. Go to Structure → Block layout, choose a region (for example Content) and place the Cache Explain block.
3. Under Visibility → Roles, restrict the block to Administrator. Optionally, under Pages, limit it to the pages you want to inspect.
4. Visit one of those pages while logged in as an administrator. The panel opens on the first layer reporting a MISS or a warning.

How it works: when the block renders, Drupal sends a HEAD request to the current page's own URL and analyses the response headers. That request carries no session cookie, so the Drupal page-cache results describe what an anonymous visitor gets, not your logged-in view. The block itself is never cached.

Things to know:

• Development and staging tool. Every time the block renders, the site makes a request to itself, which roughly doubles the work for that page. Keep it limited to administrators, and remove it from production once you've finished investigating.
• Trusted hosts. The URL requested is built from the incoming request, so make sure trusted_host_patterns is set in settings.php.
• Cache tags, contexts and max-age only appear when Drupal sends cacheability debug headers. Enable http.response.debug_cacheability_headers: true in
  services.yml on non-production environments.
• CDNs cache per data centre. The request goes out from your server, so a CDN result reflects the data centre nearest the server, which may differ from the one a visitor reaches.
• The panel needs JavaScript.

Additional Requirements

• Drupal 10 or 11.
• The core Block module (enabled on most sites).
• Your server must be able to make HTTP requests to its own public URL.

No contributed modules or external libraries are required.

Recommended modules/libraries

• WebProfiler: per-request profiling inside Drupal, including cache-bin hits and misses, which Cache Explain can't see from HTTP headers.
• Render Visualization (renderviz): explore render-array cache tags, contexts and max-age element by element from the browser console.
• Purge: once you know which layer is holding stale content, invalidate your CDN or Varnish from Drupal.

Similar projects

• Cache Review helps you learn how Drupal's Internal and Dynamic Page Caches behave, with demo pages and on-page framing. It covers only Drupal's own caches. Cache Explain also covers the browser, the CDN and the reverse proxy in front of Drupal.
• renderviz and WebProfiler look inside Drupal: render arrays, cache bins, per-request profiling. Cache Explain looks at the whole HTTP path. They answer different questions and work well together.
• Cache Debug (Drupal 7) logs calls to cache backends. It doesn't inspect HTTP caching.
• Cache Metrics sends cache activity to New Relic for production monitoring across many requests. Cache Explain inspects one page on demand.
• Purge, Akamai and similar modules clear CDN and proxy caches. Cache Explain inspects them, to show what needs clearing and why.

Supporting this Module

Bug reports, feature requests and patches are welcome in the issue queue. Support for more CDNs (Fastly, CloudFront) and reverse proxies is a good place to start.

Community Documentation

• Drupal Cache API
• Internal Page Cache
• Dynamic Page Cache
• Cloudflare cache responses (CF-Cache-Status values)