Nginx Caching – Check If Request Is Being Cached

Published on Author gryzli


If you are already using Nginx caching, you might be to the point, when you want to know if your request is being cached and served from the cache.

If you are still new to the idea of using Nginx for caching proxy, you might want to take a look at this caching configuration guide.


Knowing your cache by HTTP headers

The most popular method out there for knowing if you are seeing cached content is by using additional HTTP headers, that tells you exactly what type of content you are seeing.

I suggest you to configure 2 types of headers- first one that will show your caching status (cache hit , cache miss, …etc…) and another by which you can check how old as a date is your cache.

Adding both headers is pretty straight forward.


1) Adding cache status header

First we are going to add cache status header, which is as easy as adding the following configuration to your caching Location/Server {} sections:

server {
     add_header X-GG-Cache-Status $upstream_cache_status;


By adding this , you could easily check your caching status by using curl and checking X-GG-Cache-status header:

Checking nginx cache header with curl

You could also check your header by using Developer Tools in your browser (Firefox and Chrome can open dev tools with F12 ).

The cache status could be one of the following:


For more information check Official Documentation.


2) Adding date header

In the current free version of Nginx, there is no internal variable, that could give you information about your cache age. So you have no normal means of knowing how much time further you are going to see the same cached version of the web page.

What you could do is to add additional header, that exposes the DATE http header, which Upstream server returned for the cached web page.

By knowing this Date header, you could easily know when this resource has been cached and also how much time more, it will need to refresh (if you know your cache validity period).

This could be done by adding the following code:

server { 
     add_header X-GG-Cache-Date $upstream_http_date;


Knowing your cache by observing Nginx access logs

You already know how to check your cache status by hitting some URL address.

Now lets suppose you want to know what each of your visitors is seeing (HIT/MISS/EXPIRE …etc). This might be very useful if you want to make sure that your caching is working as expected (caching the right URL’s ).

Luckily there is an easy way of doing this by defining your custom log_format inside Nginx.

Keep in mind that log_format directive, could be used only inside http {} context.

Here is an example log_format:

http {
log_format custom_cache_log '[$time_local] [Cache:$upstream_cache_status] [$host] [Remote_Addr: $remote_addr] - $remote_user - $server_name to: $upstream_addr: "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" ' ;


Then you need to tell your site to use the custom defined log_format for access logging.

You should add the following in your server {} section :

server { 
     access_log  /var/log/nginx/ custom_cache_log ;



Finally you need to restart/reload nginx.


Your logs will look like this:

[07/Mar/2018:14:56:52 +0200] [Cache:HIT] [] [Remote_Addr:] - - - to: -: "GET /favicon.ico HTTP/2.0" 200 894 "" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.186 Safari/537.36"


Some Additional Resources

Configure Nginx For Proxying Long URL Addresses

Caching In Nginx Based on Page Size

Happy caching !