Cache keys
Look up how Azion builds a cache key from a request, what each variation adds to it, and the debug headers that show the key and the cache status.
A cache key is the index entry Cache stores an object under. Azion builds it from the request: the scheme, the host, the path, and the variations that a cache setting or Image Processor adds. A request whose key matches a valid stored object is answered with that object. Otherwise the origin or a Function builds the response, and Azion can store that response under that key. For the lookup, refer to Expiration and freshness. For the fields that add variations, refer to Cache settings.
Key format
The default key concatenates three elements of the request URI, in this order:
| Element | Example |
|---|---|
| Scheme | https |
| Host | static.example.com |
| Path | /page/site.js |
The query string is not part of the default key: https://static.example.com/page/site.js?city=city&name=name produces the same key as the URI without it. The query-string variation under Variations adds it.
The URI https://static.example.com/page/site.js produces the key httpsstatic.example.com/page/site.js. Keys are case sensitive: upper and lower case characters are distinct. When a cache setting turns a variation on, the key can end with the @@ separator, as in httpsstatic.example.com/page/site.js@@. The table under Variations shows where each variation goes: the request method is a prefix, and the other variations follow @@, the query string included when its behavior is allowlist or denylist. Under all, the whole query string follows the path, before @@.
Variations
A variation adds to the default key, so one URI can hold more than one object in the cache. The table lists what each variation adds and the key it produces.
| Variation | What it adds | Example key |
|---|---|---|
| Complex request | The request method, prefixed to the key. A GET or HEAD request carries no prefix. |
optionshttpsstatic.example.com/page |
| Query string | Under allowlist and denylist: @@, then ? and the arguments the setting keeps. Under all: ? and the whole query string, after the path and before @@. |
httpstatic.example.com/page@@?name=name, httpstatic.example.com/page?city=city&name=name@@ |
| Cookies | Under allowlist and denylist: @@, then each cookie name and value the setting keeps, followed by ;. The empty variation, with no cookie value, is @@;. Under all, the whole Cookie header follows @@ as it arrived, spaces included. |
httpwww.example.com/@@;, httpwww.example.com/@@user=user; |
| Device group | @@ and the name of the device group. |
httpwww.example.com/@@Mobile |
| Image Processor | The converted image format, at the end of the key with no separator. When the cache setting names ims in its query-string allowlist, the ims query string follows @@, and the format follows it. When the cache setting does not vary the key by query string, the ims value is not part of the key, so every size and processing of the path shares a key, and the first one stored answers every ims value. |
httpsstatic.example.com/static/images/image_1.jpg@@webp, httpsstatic.example.com/static/images/image_1.jpg@@?ims=880xwebp |
| Large File Optimization | @@bytes=<start>-<end> for each fragment, so each fragment carries its own key. A file of 2,097,152 bytes produces two keys. |
httpsstatic.example.com/media/file.mp4@@bytes=0-1048575, httpsstatic.example.com/media/file.mp4@@bytes=1048576-2097151 |
Cached POST |
@@ and the MD5 (Message Digest 5) hash of the request body, after the post prefix. A cached OPTIONS carries only the options prefix. |
posthttpsdynamic.example.com/path@@<md5-of-post-body>, optionshttpsdynamic.example.com/path |
The query-string and cookie fields are case sensitive, so user and User are two variations. With sort_enabled on in the cache setting, ?name=name&city=city and ?city=city&name=name share one key, with the arguments in alphabetical order.
The query-string, cookie, device group, and request method variations make up Advanced Cache Key, a Feature of Application Accelerator. Each of them requires Application Accelerator on the Application. For what each behavior does to the key, refer to Application Accelerator settings.
In Azion Console, these controls produce the variations, with the API field of each one in parentheses:
- Cache vary by Method (
cache_vary_by_method) makesPOSTandOPTIONSresponses cacheable. - Cache vary by Query String (
cache_vary_by_querystring) sets the query-string variation, with its Behavior and Sort. - Cache vary by Cookies (
cache_vary_by_cookies) sets the cookie variation. - Cache vary by Devices (
cache_vary_by_devices) sets the device group variation, for the groups defined in Device Groups. - Large file optimization (
large_file_cache.enabled) splits a large object into fragments, each with its own key. - Image Processor, turned on in the Application (
modules.image_processor.enabled), adds the format variation.
For the type and default of each field, refer to Cache settings.
Debug headers
To read the status and the key of a response, send the request with the header Pragma: azion-debug-cache. The response carries several x-cache-* headers, and two of them hold the status and the key. x-cache holds the cache status, the IP address of the server that answered the request, and the protocol. x-cache-key holds the key:
Under HTTP/2, the header names arrive in lower case. A GET or HEAD response that Azion does not store carries - in both headers while Application Accelerator is on; with it off, the same response reports MISS, with its key in x-cache-key and x-cache-expires-in: 0. A POST, PUT, PATCH, DELETE, or OPTIONS response that Azion does not store carries - either way. Consecutive requests for one path can each be answered by a different server, which x-cache names. For the procedure, refer to Check the cache status of a response.
Cache status
The x-cache header opens with one of eight values. Each one names what Cache did with the request.
| Status | Meaning |
|---|---|
HIT |
Valid, up-to-date content served from the cache of the data center that answered the request. The origin receives no request. |
MISS |
The content is not in the cache. Azion fetches it from the origin, and the response may be stored for later requests. |
EXPIRED |
The cached copy passed its time to live (TTL). When the origin responds, the response updates the copy for later requests. |
STALE |
Stale cache is on, the copy expired, and the origin failed to respond, so Azion serves the expired copy. |
UPDATING |
The copy expired, and Azion serves it while the content is updated from the origin. |
REVALIDATED |
Azion checked the copy against the origin with conditional headers, and it was still current, so the origin did not send it again. |
BYPASS |
The request went to the origin because a Bypass Cache behavior applies. A response under that behavior can report - instead. |
- |
No status: Azion did not store the response. A POST reports it when caching for POST is off, and a GET or HEAD response that is not stored reports it while Application Accelerator is on. With Application Accelerator off, that GET or HEAD response reports MISS with x-cache-expires-in: 0. |
For more information on the STALE status, refer to Expiration and freshness.