> For the complete documentation index, see [llms.txt](https://docs.link11.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.link11.com/product-guides/secure-cdn/interface/instances/cdn-location-cache-key.md). # CDN Location Cache Key
Each time a client sends a request, Secure CDN must decide whether to serve cached content, or to fetch a fresh response from the customer origin. This decision is based upon cache keys. When a request is received, a cache key is generated for it. If that key matches the key of a cached response, that response is served to the client. Otherwise, the request is forwarded to the origin, and its response is cached and sent to the client. The settings on this page can be used to customize the key structure. ## Cache keys and CDN performance The percentage of requests that are answered with a cached response is known as the *cache hit rate*. This is an important factor in CDN performance. The optimal rate balances two factors: * A low cache hit rate will protect delivery accuracy, so that clients always receive correct responses. * A high cache hit rate will reduce latency and the volume of requests sent to the origin. The cache key structure is an important factor in determining the hit rate: * Including more information in the key structure will produce a lower hit rate. * Including less information, and/or sorting the query string, will produce a higher rate. In other words: * A more specific cache key structure increases the amount of cached content, which improves the accuracy. * A more general cache key structure reduces the number of cache misses/origin fetches, which improves the raw performance. In general, the ideal cache hit rate is as high as possible (thus providing the best performance), while not sacrificing accuracy. To optimize the hit rate, carefully evaluate the possible query parameters, and whether they should be included in the cache key structure. Some examples: * Perhaps a certain query parameter is only needed internally (e.g. for tracking), but doesn't influence the actual cached object. This can be excluded from the key, which will improve the cache hit rate without serving incorrect content. * Conversely, a different parameter creates slight variations in content. This parameter should be included, even if it lowers the cache hit rate. Otherwise, the delivered content would not be accurate. This evaluation should not be limited to query strings; all potential parameters should be considered. For example, perhaps there's a header which creates variations in content. As explained below, headers are not included in the default cache key structure, so in this case, the structure should be customized to include it. To summarize the discussion above: in order to achieve the best performance, define the cache key structure as follows. * Include all information that's necessary to accurately cache separate resources, so that these can be served from CDN. * Exclude everything that does not meaningfully distinguish between resources, so that resources that are (for practical purposes) identical will be simultaneously stored. {% hint style="info" %} In an http request, the query string (the portion of the URL following "?") consists of key-value pairs. In the discussion below, in order to avoid confusion with cache keys, query string keys will be referred to as query arguments. {% endhint %} ## Cache key structure: default and customization By default, Secure CDN's cache keys are structured as ***protocol/host/path/query-string**.* The full query string, including all argument names and values, is included in the cache key. Thus, the following will produce unique keys: * `example.com/mypath?arg1=foo` * `example.com/mypath?arg1=bar` * `example.com/mypath?arg1=foo&arg2=bar` The *Cache Key* page allows the customization of cache key structure, according to the various components of a request. * **Protocol**: Included in the cache key by default. Can be excluded if desired. * **Query strings**: As explained [below](#query-strings-to-include-exclude), extensive customization is available for including or excluding specific arguments. * **HTTP headers**: By default, these are not included in cache keys. Specific ones can be included if desired. * **Cookies**: By default, these are not included in cache keys. Specific ones can be included if desired. {% hint style="info" %} **Host and path/URI**: As the most important parameters for mapping a request to a response, these arguments and values are always included in the cache key structure. {% endhint %} {% hint style="info" %} If a custom cache key structure is defined, but a runtime error occurs, the default structure is used instead. {% endhint %} ### When arguments are included but not present When a query argument, header, or cookie is included in the cache key structure (whether [implicitly or explicitly](#implicit-and-explicit-inclusion)), but it was not supplied in the request, this parameter is assigned a null value for comparison purposes. In other words, it will not match a key that contains a value for that parameter, but it will match a key without a value. **Example**: the query argument *arg1* is included in the cache key structure, and the following sequence of requests is received. * `example.com/mypath?arg1=foo` : a response is fetched from the origin, cached, and sent to the client. * `example.com/mypath`: this request's cache key does not match the previous request's key, so a fresh response is fetched, cached, and sent. * `example.com/mypath`: this matches the second request's key, so the second cached response is sent to the client. ### Implicit and explicit inclusion Being included in the cache key structure can happen explicitly (i.e., that parameter was specified as being included), or implicitly (certain parameters were specified to be excluded, but this parameter was not among them). ## Customization parameters ### Include Protocol When `ON`, requests to HTTP or HTTPS will result in different cache keys. ### Query String Parameters This setting works in conjunction with the following field (*Define Query Strings to include/exclude*). Its possible settings are: * **include all**: The entire query string is part of the cache key. * **exclude all**: The entire query string is ignored when constructing the cache key. * **include specific**: Specific arguments (those defined in the following field) are included in the cache key, while all others are ignored. * **exclude specific**: Specific arguments (those defined in the following field) are ignored, while all others are included in the cache key. {% hint style="info" %} Inclusions and exclusions are based on query argument names, not values. For example, `arg1` can be either included or excluded; it is not possible to include `arg1=foo` but exclude `arg1=bar`. {% endhint %} ### Query Strings to include/exclude This field is available when *Query Strings* is set to either `include specific` or `exclude specific`. Here, the arguments to include or exclude are defined. * Included query arguments are used when constructing cache keys; all other arguments are ignored. * Excluded query arguments are ignored when constructing cache keys; all other arguments are included. {% hint style="info" %} For arguments that can vary significantly (e.g., those with high cardinality) without affecting the content of the response, excluding them can improve CDN performance. {% endhint %} #### Examples *Query Strings* is set to `include specific`, and *Define Query Strings to include/exclude* is set to `arg1`. * `mypath?arg1=foo` will result in a fetched and cached response with a new cache key. * `mypath?arg1=foo&arg2=bar` will match that key; the cached response will be served. * `mypath?arg1=bar` will not match, and will result in a second response/key. * `mypath` will not match either the first or second keys, and will result in a third response/key. On a different site, *Query Strings* is set to `exclude specific`, and *Define Query Strings to include/exclude* is set to `arg1`. * `path?arg1=foo` will result in a fetched and cached response with a new cache key. * `path?arg1=bar` or `path` will match the previous key; the cached response will be served. * `path?arg1=foo&arg2=bar` will not match (because arg2 is implicitly included), and will result in a second response/key. ### Sort Query String By default, query strings are examined as they were supplied in the request. Turning this setting `ON` will alphabetically sort the arguments in the query string before this examination. If the order of query string arguments is not important, enabling this feature can result in a higher rate of cache hits, resulting in improved system performance. **Example**: when this setting is `OFF`, the query strings below will produce different cache keys. * `arg2=bar&arg1=foo&arg3=plugh` * `arg3=plugh&arg1=foo&arg2=bar` * `arg1=foo&arg3=plugh&arg2=bar` With this setting `ON`, after sorting they all become `arg1=foo&arg2=bar&arg3=plugh`, so they will all produce the same key. Therefore, all three requests will receive the same cached response. ### **HTTP Headers** By default, headers are not included in the cache key structure. Adding header names to this list will include those header names/values in the keys. As noted in WebGUI, certain headers are excluded from this feature, for security and performance reasons. [Here](#when-arguments-are-included-but-not-present) is a note about included headers that are not supplied in the request. ### Cookies By default, cookies are not included in the cache key structure. Adding cookie names to this list will include those cookie names/values in the keys. As noted in WebGUI, including cookies with uncommon or unique values will reduce the cache hit rate. [Here](#when-arguments-are-included-but-not-present) is a note about included cookies that are not supplied in the request.