Introduction
When Cloudflare proxies HTTP traffic, we also offer the opportunity to cache content on our infrastructure, meaning:
- The visitors to your site receive the content faster. We can serve the content closer to your users, thanks to our global network of data centers.
- You’ll receive fewer requests to your web infrastructure, saving you bandwidth and reducing the load on your servers.
Caching on Cloudflare
When a web request passes through Cloudflare, it goes through various layers starting with our security layers. The final layer is the caching layer.
If Cloudflare has an asset (such as an image file) in cache, it will be served from the cache, and if not, we will request the asset from your web server (we refer to this as the origin).
By default Cloudflare only caches static content based on a defined list of file extensions - this includes assets such as .jpg, .gif or .pdf for example. If you want to cache content that doesn’t exist on our static content list (e.g. .html or .php) you can do so using page rules.
Our caching system stores items in cache based on a cache key - in essence, if the cache key matches, we can serve that asset from cache instead of requesting the asset from origin.
Out of the box, Cloudflare caching is driven by URL - if the URL matches, then we can serve the item from cache. This behavior can be modified with custom cache keys, a feature only available on our Enterprise plan.
What is a custom cache key?
It is possible to extend caching to something more specific than just the URL, using our custom cache keys feature.
A custom cache key defines what information in the visitor's HTTP request is used to find a matching item in the cache, as such custom cache keys are generally used in two simple ways:
- To make caching more granular when the origin generates different responses based on something other than the URL. For example, you may want to cache and serve a different image file depending on whether the user is requesting the asset from a mobile, tablet or desktop.
- To increase the cache hit rate for requests that would normally create separate cache items. For example, if you had an asset requested with a unique session ID (e.g. image.jpg?session=uniquesessionID) you would not want to cache the asset for every unique session. Instead, it would be better to ignore the query string and serve the one asset for all requests.
For example, here is our default cache key for all cache levels except ignore query string:
|
${header:origin}::${scheme}://${host_header}${uri} |
So when a typical request for https://www.example.com/something is made, this would create a very simple cache key like this:
|
::https://www.example.com/something |
Note if this were a cross-origin request from anotherdomain.com the origin HTTP request header would be sent, meaning the ${header:origin} token would be populated, resulting in a cache key like:
|
anotherdomain.com::https://www.example.com/something |
Here's what our cache key looks like when Ignore Query String caching is in effect:
|
${header:origin}::${scheme}://${host_header}${uri_iqs} |
${uri_iqs} is replaced with the request path excluding the query string, so a request http://example.com/file.jpg?something=123 would create this cache key:
|
::http://example.com/file.jpg |
Thus achieving "Ignore Query String" caching.
So you can think of Custom Cache Keys as being similar to Ignore Query String, but with the ability to vary on all sorts of aspects of the HTTP request.
How do I use custom cache keys?
They are implemented using page rules. A Cloudflare team member will add a page rule for you containing the agreed custom cache key. The custom cache key will only apply when the URL match occurs.
For example:
You will be able to edit all aspects of the page rule, but not modify the custom cache key itself. Only Cloudflare can adjust the key on your behalf.
What can be added to the custom cache key?
The following elements can be used in custom cache keys:
- Scheme - whether the request is http or https
- Geo - the country of origin the visitor is coming from (two letter country code)
- Language - based the Accept-Language header provided by the browser (trimmed to the first language)
- Cookie test - whether a cookie is provided by the browser or not (would use a 0 or 1 in the cache key)
- Cookie content - the full value of the cookie (only available under certain circumstances)
- Header test - whether a particular request header is provided by the browser or not (would use a 0 or 1 in the cache key)
- Header content - the full value of the particular header
- Device type - one of mobile, tablet or desktop
The aim of custom cache keys is to reduce the number of different objects in our cache. Please note we cannot implement custom cache keys which will significantly duplicate the number of objects in our cache. Please discuss your exact requirements with your solutions engineer.
Caveats
Right now “Purge Individual Files” in our control panel will not work if the cache key has varied from the default. In order to purge assets with a custom cache key you will need to purge by tag or purge everything.
How do I get started?
Please contact your designated solutions engineer who will be happy to assist in getting custom cache keys setup.