Observing layered caches with Cache-Status

Core idea

Cache-Status represents decisions from one or more caches as a Structured Fields list. hit, fwd, ttl, and detail identify a layer only when read alongside Cache-Control, Age, Vary, and validators.

For Observing layered caches with Cache-Status, split speed into connection latency, time to first byte, and transfer throughput. A tiny response mainly measures latency; a large file may hit the client or server link. Use a series of identical requests and a direct baseline from the same time window.

What the primary source establishes

Read browser, edge, and origin-cache decisions through a standard field while validating Age, validators, and origin version.

The primary source, RFC 9211 — Cache-Status, RFC 9111 — HTTP Caching, RFC 9651 — Structured Fields, RFC 9209 — Proxy-Status, RFC 9110 — HTTP Semantics, defines the technical baseline but not every client and provider configuration. Read the normative behavior with its version and then verify your implementation. Treat anything beyond the source as a product feature that needs separate confirmation.

Controlled lab

Increment an origin version during a controlled publish. Require origin fetch, warm hit, expiry revalidation, and a new version after publish. Corrupt one Cache-Status element and verify that the monitor reports a parse error separately from page availability.

Step-by-step verification

Serve versioned JSON with explicit caching from an owned route. Run a cold request, warm hit, forced revalidation, and origin update. Give two cache layers distinct safe identifiers and inspect list order.

Host a small latency response and a known-size file on a controlled server. Warm up once, then collect at least five direct and five proxied measurements. Use one connection for route testing and separately reproduce normal concurrency when evaluating the real application.

Record DNS, connect, TLS, first byte, total time, and bytes. Compare medians. A slow first request can indicate DNS, TLS, or a cold cache; slow large transfers point to capacity, loss, or server limits. Rotating an IP without these measurements proves nothing.

• Fetch a cold response
• Confirm a warm hit
• Trigger revalidation
• Verify the new origin version

Evidence to retain

Record Cache-Status chain, Age, Cache-Control, ETag, Vary, body version, HTTP status, and origin request ID. Do not treat the header as the sole source of truth.

Include file size, endpoint region, access type, raw values, and median. A 10 MiB check measures the path from the client to the WorldProxy test endpoint through that proxy, not the speed of the whole internet. Treat fast HTTP errors as failed checks, not performance successes.

Define report columns and time format before the run. A result without context becomes a guess: the address, cache state, and changed condition are unknown. Record controlled failures as well as successes so the check proves that it can distinguish states.

Interpreting the result

A hit does not prove freshness by itself; compare body version and validator with the origin. Parsers should tolerate unknown extension parameters without treating malformed fields as success.

The field is optional and can be shortened or changed by intermediaries. Private browser caches need not appear in the response.

One successful run confirms only one client, route, and moment. Repeat while changing one variable and state the limits. When observation conflicts with documentation, rule out cache, client version, and intermediaries before creating a reproducible support case.

Worked decision process

Define a measurement budget for Observing layered caches with Cache-Status: warm-up, five small requests, five known-file transfers, the same direct controls, fixed concurrency, and a pause between heavy cycles. Estimate billable traffic before running the test.

Separate latency from throughput. A small response exposes DNS, connect, TLS, and first-byte cost. A 10 MB file measures the path from the client to the WorldProxy endpoint through the selected proxy, not universal internet speed. Test a browser workload separately when connection reuse matters.

Confirm anomalies against a direct route, another exit in the same geography, and a delayed repeat. Keep median, spread, and failure count. A best result hides instability, while an average can be distorted by one hang.

Common mistakes

Do not compare morning Wi-Fi with evening Ethernet, different files, or different CDN nodes. Avoid unlimited timeouts and repeated heavy checks. They consume traffic and create their own queue. Run a bounded sample, pause, and repeat only anomalies.

Stop when errors rise, a source returns a limit, the task would require bypassing protection, or secrets enter logs. Save sanitized diagnostics and correct the cause first. More concurrency or another IP can hide the fault and add load without improving evidence.

Rollout and maintenance criteria

Define the decision boundary before rollout: which observation permits continuation, which requires review, and which stops the workflow. Record acceptable error ratio, maximum wait, and the owner of every exception so a temporary failure cannot silently become permanent configuration.

Review real load, cost, and quality after the first week. Schedule a small control after client, proxy-service, or network changes. Archive outdated instructions with their replacement date and reason so operators do not follow conflicting configurations.

Operational checklist

Turn the successful experiment into a short procedure covering owner, safe configuration, limits, and stop conditions. Every run needs a terminal status. After browser, library, or network changes, run a small control before the main queue.

• A direct baseline exists
• File and endpoint match
• Phases are recorded
• Median is used
• Errors are separate
• Measured path is stated