Varnish Cache’s Configuration Language (VCL) can be very approachable to get started with basic caching behaviour for your website. However, once you start to leverage the power of VCL to achieve the best possible performance for your site, you can find yourself in a situation where some HTTP requests don’t appear to be behaving how you expect. Varnish Cache has some great tools to help you troubleshoot.
Varnishlog is my preferred tool for these scenarios. By default it allows you to see the HTTP request and response lines, the HTTP headers that are received, modified, and sent, and the VCL subroutines that are called as each request is handled by Varnish Cache. This capability alone is extremely useful but there are at least two other options you can enable to improve it even further.
The first option is to change the Varnish Cache’s vsl_mask Run Time Parameter to log VCL_trace messages to Varnish Cache’s Shared-memory Log (VSL) from which varnishlog reads. In almost every version of Varnish Cache, you will then see in varnishlog an extra line labelled VCL_trace reporting the line number and character position within your VCL as each VCL statement is executed. This makes it easier to follow the path through your code and why particular headers are modified or particular subroutines get called.
In Varnish Cache 5.2.0, the VCL_trace messages were extended to also include the VCL configuration name and the program source index to help when debugging code that leverages the VCL Labels feature first introduced in Varnish Cache 5.0.
The second option is to change Varnish Cache’s vsl_reclen Run Time Parameter to increase the maximum size of an entry in the VSL. By default, the vsl_reclen is capped at 255 bytes which means that entries can be truncated, especially the ReqURL, ReqHeader, and RespHeader entries if your site uses particularly long query strings or many long cookies. When your VCL is making decisions based on these values, but the relevant portion has been omitted from the log, it can be very confusing trying to following the logic.
The VCL_trace option is already enabled in vclFiddle, and both options can be controlled in Section’s Developer PoP via the proxy-features.json file. These options are typically left in their default states in Production Varnish Cache deployments however since they can have an impact on workspace memory usage and also on shared-memory lock contention during Production-level high-traffic situations.
