Cache observability
Understand cache hits, misses, bypasses, revalidation, and origin work.
Cache observability explains whether Easel served a response from cache or performed additional work.
Cache outcomes
Easel exposes cache processing through the X-Easel-Cache response header and
related Logs filters.
| Status | Meaning |
|---|---|
| HIT | A fresh cached response was served |
| STALE | A stale cached response was served within an explicit stale-while-revalidate window while refreshing in the background |
| MISS | No usable fresh or SWR-eligible stale entry was found; origin or regeneration ran |
| BYPASS | The request or response was not eligible for shared caching |
| ERROR | Cache processing encountered an error path |
Treat X-Easel-Cache as authoritative for whether Easel reused a cached
response. See Caching and
CDN headers.
Definitions
HIT
The response was served from cache without invoking the application origin or function for that response body.
MISS
No usable cached response existed, so Easel fetched or generated one.
BYPASS
The request did not use shared cache because of request properties, response
headers, or policy (for example Authorization, Set-Cookie, private, or
missing shared TTL).
STALE
A stale entry was eligible under stale-while-revalidate and was served while
Easel refreshed in the background.
Security and cache
Security controls run before cache lookup. A blocked or challenged request does not proceed to ordinary application cache serving. See Security evaluation order.
Runtime Cache panel
On Observability, the Runtime Cache panel summarizes project-scoped runtime cache operations such as reads, hits, misses, writes, revalidations, and evictions for frameworks that use Easel’s runtime cache APIs.
See Runtime Cache.
Debugging workflow
- Reproduce the request and read
X-Easel-Cache. - Confirm cache headers on the origin response (
Cache-Control, cookies). - Filter Logs by cache status when available.
- For ISR or runtime-cache issues, check revalidation docs and the Runtime Cache panel.