Confirming Varnish cache status for a page

When working with Varnish and developing your configuration, you will be interested to know how well things are being cached.

Your VCL can instruct Varnish to cache or not cache things depending on certain situations. In fact, the VCL is more like a programming language. For a programmer within you, I’ve got this complicated definition:

VCL is a programming language with instructions for Varnish (the “interpreter”) on how you want various page requests to be run through Varnish state machine.

Pedantic me should have rather called this post “Confirming Varnish cache status for a particular request“, but opted for a somewhat simpler title.

What we always want to know simply goes down to:

“How do I know that this page I’ve just loaded was delivered from Varnish cache (and not from backend)?”.

HTTP headers specific to Varnish

Out of the box, Varnish already emits one useful header for checking cache status of each request: X-Varnish. All you need to know is how to interpret its value:

• A value with two integers means that the page was delivered from the cache.
• A value with single integer means that the page was delivered directly from the backend.

Another header – Age, can be present if you use other caching software as well. Varnish makes use of it to indicate how long the page was in its cache.

How you inspect those headers’ values depends on your willingness to use command line or browser.

Use command line to check HTTP headers

The most trivial way for me would be using curl and issue a HEAD request to the page to inspect X-Varnish value.

curl -IL http://example.com/

The -I switch is for HEAD request method and emitting resulting values to the standard output
The -L is for following whichever HTTP redirects the page in question may have.

For a page that was delivered from cache, output would be similar to this:

HTTP/2 200
server: nginx
date: Sat, 20 Jan 2018 10:00:11 GMT
content-type: text/html; charset=UTF-8
x-varnish: 820734 2294086
age: 49

The age header, in this case, will correspond to the time in seconds of how long the page has been already cached.

An uncached page will emit something like the following:

HTTP/2 200
server: nginx
date: Sat, 20 Jan 2018 10:00:11 GMT
content-type: text/html; charset=UTF-8
x-varnish: 820734 
age: 0

Using browser to check HTTP headers

You may want to use just your browser to inspect HTTP headers. Modern browsers have everything you need to do it. Let’s take Chrome for example.

First, load a particular page, then right click anywhere on it and select “Inspect”.

You will now see developer tools open. Next, click on Network tab.

Now reload the page. The developer tools will record all the network requests while loading the page. The topmost request corresponds to the page itself (HTML). Select it by clicking on it:

On the right side, you will see details about the request. We are interested in Headers tab. After selecting it, scroll down to “Response Headers”. Now you can see X-Varnish in there (and/or X-cache).

Talking about the X-cache header. It’s a convenience header which you might have been using already. Many VCL snippets you may find online include this:

sub vcl_deliver {
    if (obj.hits > 0) {
        set resp.http.X-Cache = "cached";
    } else {
        set resp.http.X-Cache = "uncached";
    }
}

If you already know how to read the X-Varnish header value, you can safely remove this snippet to declutter your VCL.

Visual browser check

As I’ve been monitoring StackExchange forums, I’ve stumbled on an interesting question:

How do you check Varnish cache status for a particular page by changing its background, in an elegant way?

As I’ve just mentioned, typically, you already have some VCL to create X-Cache convenience header. You can expand it to insert CSS stylesheet using Link header. Note that this would only work in Gecko-based browsers like Firefox:

sub vcl_deliver {
    if (obj.hits > 0) {
        set resp.http.X-Cache = "cached";
    } else {
        set resp.http.X-Cache = "uncached";
        set resp.http.Link = "</miss.css>;rel=stylesheet;type=text/css;media=all";
    }
}

Naturally, you need to create the miss.css stylesheet in the web root of your site. It should have specific styles that you want to be applied when a page was not delivered from the cache.

I hope that’s all there is to it for checking Varnish page cache status 🙂