Cache keys
Look up how Azion builds a cache key from a request, what each variation appends 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 a cache setting adds. A request whose key matches a stored object is answered from the copy. Otherwise the request goes to the origin, and Azion stores the 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 four elements of the request URI, in this order:
| Element | Example |
|---|---|
| Scheme | https |
| Host | static.example.com |
| Path | /page/site.js |
| Variation separator and variations | @@Mobile |
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@@. Each variation listed under Variations is appended after that separator.
Variations
A variation appends to the default key, so one URI can hold more than one object in the cache. The table lists what each variation appends and the key it produces.
| Variation | What is appended | 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 | The ? separator and the arguments the setting names, in the order the request sends them. With Sort on, ?name=name&city=city and ?city=city&name=name share one key, with the arguments in alphabetical order. | httpstatic.example.com/page?name=name, httpstatic.example.com/page?city=city&name=name, httpstatic.example.com/page?name=name&city=city |
| Cookies | @@, then each cookie name and value the setting names, followed by ;. The empty variation, with no cookie value, is @@;. | httpwww.example.com/@@;, httpwww.example.com/@@user=user; |
| Device group | @@ and the name of the device group. | httpwww.example.com/@@Mobile |
| Image Processor | The ims query string, and the converted image format after @@. | httpsstatic.example.com/static/images/image_1.jpg?ims=880x@@webp |
| Large File Optimization | @@bytes=<start>-<end> for each fragment, so each fragment carries its own key. A file of 2,097,151 bytes produces two keys. | httpsstatic.example.com/media/file.mp4@@bytes=0-1048575, httpsstatic.example.com/media/file.mp4@@bytes=1048576-2097151 |
Cached POST or OPTIONS | @@ and the MD5 hash of the request body. | httpsdynamic.example.com/path@@md5_of_post_arguments, httpsdynamic.example.com/path@@md5_of_options_arguments |
The query-string and cookie fields are case sensitive, so user and User are two variations. For a cached POST or OPTIONS request, the request body is part of the key. The query-string, cookie, device group, and request method variations are the feature named Advanced Cache Key. For what each behavior does to the key, refer to Application Accelerator settings.
These controls produce the variations:
- Cache vary by Method caches
POSTandOPTIONSrequests. - Cache vary by Query String, with its Behavior and Sort, sets the query-string variation.
- Cache vary by Cookies sets the cookie variation.
- Cache vary by Devices sets the device group variation, for the groups defined in Device Groups.
- Large file optimization splits the object into fragments, each with its own key.
- Image Processor adds the format variation.
For the field behind each control, 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 two headers. 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 response the platform does not cache carries - in both headers. 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 nearest to the user. The origin is not reached. |
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 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. For more information, refer to Expiration and freshness. |
UPDATING | The copy expired, and Azion serves it while the content is updated from the origin. For more information, refer to Expiration and freshness. |
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. |
- | No status: the content is restricted from caching. For example, a POST request when caching for POST is off. A GET or HEAD response that a function builds can carry it too. |