Check the cache status of a response

Send one request with a debug header and read whether Azion served the response from its cache, together with the key the copy is stored under.

Last updated

View as Markdown Agent setup

You check whether Cache served a response from a stored copy by requesting the object with a debug header and reading two response headers. The check runs from any machine with curl, and it needs no change to the application.

The same response carries the cache key the copy is stored under, which is the argument a cache key purge takes. For the key format and every status value, refer to Cache keys.

Prerequisites

  • curl on your machine.
  • The URL of an object your application serves.

Request the debug headers

The request header Pragma: azion-debug-cache makes Azion return the cache state of the response. To read it:

Request the object with the debug header

The -I flag asks for the response headers alone, so the body is not downloaded:

curl -sI -H "Pragma: azion-debug-cache" https://www.example.com/static/site.js
Read the cache status

The x-cache header carries three values: the cache status, the IP address of the server that answered the request, and the protocol. Under HTTP/2, the header names arrive in lowercase:

HTTP
01x-cache: MISS from 192.0.2.10 with HTTP/2.0
02x-cache-key: httpswww.example.com/static/site.js
Read the cache key

The x-cache-key header carries the key the copy is stored under. A cache key purge takes that value as its argument.

Run the same command again

Compare the status of the second response with the first.

You now know whether the response came from the cache, from the origin, or was not cached at all.

In the Build and run marketing websites use case, expect:

  • Pages answer from cache. The second request for a page, such as /about/, carries x-cache: HIT. The first can carry MISS, while Azion reads the page from the bucket.

In the Deploy frontend applications use case, expect:

  • Interface files come from cache. The second request for a script of the build, sent with the Pragma: azion-debug-cache header, carries x-cache: HIT. Its path is in a <script> tag of the entry HTML. For how to read the header, refer to Read the status.

In the Accelerate websites and APIs with a CDN use case, expect:

  • Static files answer from cache. The second request for https://www.example.com/static/app.css carries x-cache: HIT. The first can carry MISS, while Azion fetches the file.
  • Pages answer from cache. The second request for the home page carries x-cache: HIT.

Read the status

HIT means the response was served from a stored copy and the origin was not asked. MISS means the object was not in the cache, so Azion fetched it from the origin and may store the response for later requests. A - in both headers means the content is restricted from caching.

The other values a response can carry are EXPIRED, STALE, UPDATING, REVALIDATED, and BYPASS. For what each one means, refer to Cache keys.

A - on a POST or OPTIONS request means caching is off for that method. To turn it on, refer to Cache POST and OPTIONS responses.

In the Protect public APIs from abuse use case, expect:

  • Cacheable responses do not reach the origin. Request a route your cache setting covers twice, with the Pragma: azion-debug-cache header. The second response carries x-cache: HIT.

Next steps

Cache keysThe key format, every variation it can carry, and all eight cache status values.Troubleshoot ApplicationsWhat to check when a response carries no status, or stays MISS on every request.Purge cached contentRemove the copy this key names, before its TTL ends.Expiration and freshnessWhy a request is answered from a copy, from the origin, or not cached at all.Build and run marketing websitesA marketing site served from Object Storage through Cache and purged after each deploy.Deploy frontend applicationsA single-page application whose API calls reach an existing backend under the same domain.Accelerate websites and APIs with a CDNTwo cache settings, one with Tiered Cache, that serve a site's static files and pages near its users.Protect public APIs from abuseAn API whose rate limit runs last, after WAF, a token check, and Bot Manager.