We've been making changes to how we organize and display our docs. Our work isn't done but we'd love your feedback.
Getting started
Basics
Domains & Origins
Performance

Configuration
Basics
Conditions
Dictionaries
Domains & Origins
Request settings
Cache settings
Headers
Responses
Performance
Custom VCL
Image optimization
Video

Security
Access Control Lists
Monitoring and testing
Securing communications
TLS
Web Application Firewall

Integrations
Logging endpoints
Non-Fastly services

Diagnostics
Streaming logs
Debugging techniques
Common errors

Account info
Account management
Billing
User access and control

Reference

    Understanding cache HIT and MISS headers with shielded services

      Last updated June 10, 2019

    Here's some help deciphering cache hit and miss headers when you have shielding enabled.

    The cache headers

    Let's look at the following requests for the same object if you had run a cURL command in your terminal (for example, curl -svo /dev/null www.example.com) to return the Fastly headers.

    The first request for an object using the above cURL command might produce output something like this:

    1
    2
    3
    
    X-Served-By: cache-iad2120-IAD, cache-sjc3120-SJC
    X-Cache: MISS, MISS
    X-Cache-Hits: 0, 0
    

    For this first request, the two cache-nodes in X-Served-By show that shielding is turned on, with cache-iad2120-IAD serving as the delivering cache node at the shield datacenter and cache-sjc3120-SJC serving as the delivering cache node at the "local" datacenter. The X-Cache: MISS, MISS indicates that the requested object was neither in the shield cache (a MISS) nor the local delivering node (also a MISS). The X-Cache-Hits reflects that same MISS information because it displays 0, 0.

    The second request for an object using the above cURL command might produce output something like this:

    1
    2
    3
    
    X-Served-By: cache-iad2120-IAD, cache-sjc3120-SJC
    X-Cache: MISS, HIT
    X-Cache-Hits: 0, 1
    

    This second time, we hit the same local cache-node (cache-sjc3120-SJC) and got a HIT. The MISS listed for cache-iad2120-IAD reflects the state of that node the last time it was queried for that object and not its current state, which at the time of the first request, was a MISS. The object is now cached in both datacenters.

    Waiting a minute or two and requesting the same object a third time using the above cURL command might produce output something like this:

    1
    2
    3
    
    X-Served-By: cache-iad2120-IAD, cache-sjc3122-SJC
    X-Cache: MISS, HIT
    X-Cache-Hits: 0, 1
    

    This third request shows a new cache (cache-sjc3122-SJC) being selected from the local datacenter. It registers as a HIT as the object is cached in the local datacenter, with the MISS still reflecting the state of the shield datacenter when it was originally requested. The X-Cache-Hits shows 0, 1 reflecting the 0 from the shield datacenter and the 1 for the first hit on cache-sjc-3122-SJC.

    Keep in mind that if the closest delivering cache node exists in the shield datacenter, you will only see a single server and HIT data such as:

    1
    2
    3
    
    X-Served-By: cache-iad2120-IAD
    X-Cache: HIT
    X-Cache-Hits: 1
    

    After a purge of the object, requesting the object again via the above cURL command will produce results similar to the first request scenario. For example:

    1
    2
    3
    
    X-Served-By: cache-iad2120-IAD, cache-sjc3120-SJC
    X-Cache: MISS, MISS
    X-Cache-Hits: 0, 0
    

    The x-cache header

    Let's look at all the possible combinations of MISS and HIT we can see in the X-Cache header when a request is run through a both an edge and a shield datacenter.

    1
    
    X-Cache: MISS, MISS
    

    The header returned a MISS on both the shield and the edge, indicating the requested object was neither in the shield cache nor the edge cache.

    1
    
    X-Cache: MISS, HIT
    

    The header was a HIT on the edge. When the object was previously cached on this datacenter, it had been a MISS on the shield. The object cached the MISS status on the shield on the edge.

    1
    
    X-Cache: HIT, MISS
    

    The header returned a MISS on the edge and a HIT on the shield. This shows that the edge datacenter did not have the object, but when the request was forwarded to the shield datacenter, the object was found.

    1
    
    X-Cache: HIT, HIT
    

    The header returned a HIT on the edge. On a previous request, the request was forwarded from the edge datacenter to the shield datacenter to retrieve the object. Because the shield had the object, the response back to the edge showed that the shield was an X-Cache: HIT. When the object was cached on the edge, the HIT status for the shield was cached along with it. On this subsequent request, the header shows the HIT on the shield as well as the HIT on the edge.

    Back to Top

    Additional resources: