Skip to main content

How to add the X-Cache-Status header to NGINX to assist with optimizing and troubleshooting cache settings

Austin Lowery
  • Updated

Introduction

 

You may use the following steps to add the X-Cache-Status header to all of the responses that NGINX serves to help determine what responses have served from Cache and what responses have not been served from cache.

 

Procedure

 

  1. Login to the server as the root user via SSH or Terminal
  2. Create the following file: 
    touch /etc/nginx/conf.d/x-cache-status.conf
  3. Open the file with the text editor of your choice and add the following contents: 
    add_header X-Cache-Status $upstream_cache_status;
  4. Use the following command to reload the configuration so that all responses will now contain the X-Cache-Status header: 
    /scripts/ea-nginx reload

 

The following are the possible values for $upstream_cache_status, which would be what is provided within the response header:

 

MISS – The response was not found in the cache and so was fetched from an origin server. The response might then have been cached.
BYPASS – The response was fetched from the origin server instead of served from the cache because the request matched a proxy_cache_bypass directive. The response might then have been cached.
EXPIRED – The entry in the cache has expired. The response contains fresh content from the origin server.
STALE – The content is stale because the origin server is not responding correctly, and proxy_cache_use_stale was configured.
UPDATING – The content is stale because the entry is currently being updated in response to a previous request, and proxy_cache_use_stale updating is configured.
REVALIDATED – The proxy_cache_revalidate directive was enabled and NGINX verified that the current cached content was still valid (If-Modified-Since or If-None-Match).
HIT – The response contains valid, fresh content direct from the cache.

Related articles