varnishlog

Display logs in real time

$ varnishlog

$ varnishlog -q 'ReqHeader eq "Host: [example.com]"'

$ varnishlog -q 'ReqMethod eq "[POST]"'

$ varnishlog -q 'ReqURL eq "/[path]"'

$ varnishlog -q 'ReqURL ~ "[regex]"'

varnishlog [options]

-a
    Associate all log records with their request ID, even if they are not directly related to a specific client or backend transaction.

-b
    Display only log records pertaining to backend requests (VCL_pipe, VCL_pass, VCL_fetch).

-c
    Display only log records pertaining to client requests (VCL_recv, VCL_deliver).

-d
    Daemonize; run varnishlog in the background.

-D
    Stop processing and exit when the Varnish Cache daemon (varnishd) exits.

-E
    Dump raw VSM data in human-readable format. Primarily for debugging Varnish itself.

-f file
    Read shared memory log from the specified file instead of the live VSM.

-g grouping
    Specify the grouping mode for log records. Common values include request (group by request ID), session (group by session ID), and raw (no grouping, show records as they appear).

-h
    Display a help message and exit.

-i tag
    Include only log records with the specified tag (e.g., ReqStart, Hit, Miss, VCL_Log). Can be used multiple times.

-I regex
    Include only log records whose content matches the specified regular expression.

-k k-bytes
    Specify the size of the VSM file in kilobytes. Useful when debugging VSM issues.

-L limit
    Limit the number of log lines to process before exiting.

-M regex
    Include only transactions whose request or response details match the specified regular expression.

-n name
    Specify the name of the Varnish instance to connect to. This is useful when multiple Varnish instances are running.

-q query
    Specify a VSL query expression to filter log records. This allows for complex filtering based on tags, levels, and values.

-r file
    Read log data from a binary file previously created with the -w option.

-R seconds
    Retry connecting to Varnish after a specified number of seconds if the connection is lost.

-S limit
    Maximum number of VSM bytes to skip if the VSM pointer is ahead of the current reading position.

-t seconds
    Timeout for transaction end. If a transaction doesn't end within this time, it's displayed anyway.

-T seconds
    Transaction timeout. If a transaction takes longer than this, it will be considered incomplete and dropped unless -t is also used.

-u
    Unbuffered output. Forces output to be written immediately without buffering.

-v
    Verbose output. Increase verbosity level, showing more detailed information, especially for debugging.

-w file
    Write log data to the specified binary file for later analysis (e.g., with -r).

-x tag
    Exclude log records with the specified tag. Can be used multiple times.

-X regex
    Exclude log records whose content matches the specified regular expression.

-z seconds
    Flush delay. Wait for this many seconds before flushing records for a transaction if it's still active.

The varnishlog command is a utility within the Varnish Cache suite, designed to provide real-time insight into the operations of a running Varnish instance.

It reads structured log data directly from Varnish's shared memory (VSM), presenting a continuous stream of events related to client requests, backend fetches, cache hits, cache misses, and various internal Varnish processes. This real-time visibility is invaluable for debugging configuration issues, monitoring performance, understanding caching behavior, and tracking the lifecycle of individual HTTP requests as they pass through the Varnish cache.

varnishlog allows for extensive filtering and grouping of log entries, enabling users to focus on specific types of events, individual client or backend transactions, or even specific VCL actions, making it an indispensable tool for Varnish administrators and developers.

varnishlog requires access to the Varnish Shared Memory (VSM), meaning it needs appropriate permissions to read from the Varnish instance's shared memory segment. If Varnish is not running, or the specified instance name (via -n) is incorrect, varnishlog will not be able to retrieve live log data.

Without proper filtering, the output can be very verbose, especially on busy Varnish servers, making it difficult to find specific information. It's crucial to utilize filtering options like -i, -x, -q, and grouping options like -g.

One of varnishlog's most powerful features is its ability to filter and group log entries. Using options like -g (grouping by request or session), -i (including specific tags), -x (excluding specific tags), and especially -q (VSL query expressions), users can precisely tailor the output to display only relevant information. This is essential for navigating large volumes of log data and quickly identifying patterns or issues.

While primarily a real-time monitoring tool, varnishlog can also be used for offline analysis. The -w option allows users to write the live log stream to a binary file, which can then be replayed and analyzed later using the -r option. This is useful for capturing specific events or for detailed post-mortem debugging without continuously watching the live stream.

varnishlog has been a core component of the Varnish Cache distribution since its early versions. As Varnish Cache evolved, so did varnishlog, gaining more sophisticated filtering capabilities (like VSL query expressions) and output options to help users better understand complex caching behaviors and debug performance issues. Its design to read directly from shared memory reflects Varnish's high-performance architecture, minimizing impact on the main Varnish process.

varnishd(1), varnishadm(1), varnishstat(1), varnishncsa(1), varnishtop(1), vsl(7), vsl-query(7)