Varnish Custom Statistics



vcs-agent [-d] [-D] [-g] [-h] [-k <key>] [-m <max>] [-p <zmq port>] [-P <file>] [-n <dir>] [-t <seconds|off>] [-V] host


The vcs-agent utility reads varnishd(1) shared memory logs and produces log records to be consumed by vcs(8).

Each log record is tagged with a set of keys defined through VCL in the configuration of the local varnishd(1) instance.


-d Generate default URL, HOST, and ALL keys.
-D Daemonize.
-g Output debug information.
-h Display help. Displays a brief list of vcs-agent's options, along with default values.
-k <key> Prefix used for matching varnishlog key definitions. The default value is "vcs-key".
-m <max> Limit for the number of messages vcs-agent should queue in the event that vcs is unreachable. After reaching this limit, messages will be dropped. A value of 0 means "no limit".
-p <zmq port> Remote port used when connecting to vcs(8).
-P <file> Write the process' PID to the specified file.
-n <dir> Specify the varnishd working directory (also known as instance name) to get logs from. If -n is not specified, the host name is used.
-t <seconds|off>
 Timeout before returning error on initial VSM connection. If set the VSM connection is retried every 0.5 seconds for this many seconds. If zero the connection is attempted only once and will fail immediately if unsuccessful. If set to "off", the connection will not fail, allowing the utility to start and wait indefinetely for the Varnish instance to appear. Defaults to 5 seconds.
-V Print version information and exit.


The VCS host used for aggregating counters.
--optstring Print the optstring parameter to getopt(3) to help writing wrapper scripts.


Keys are defined in VCL, by writing an std.log() entry prefixed with the string "vcs-key". Multiple definitions for the same request are permitted. Typically this is done in vcl_deliver. Use -d to have the default keys generated for you.

Unique counting

Setting up "unique counting" is done by issuing an std.log() entry prefixed with "vcs-unique-id:".


VCL Configuration

Configuring the key definitions in VCL may look like this:

sub vcl_deliver {
  std.log("vcs-key:" + + req.url);
  std.log("vcs-key:" +;

  if (obj.hits == 0) {


This document was written by Dag Haavi Finstad <>.