vcs-agent

SYNOPSIS

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

DESCRIPTION

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.

OPTIONS

-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 indefinitely for the Varnish instance to appear. Defaults to 5 seconds.

-V Print version information and exit.

host The VCS host used for aggregating counters.

--optstring Print the optstring parameter to getopt(3) to help writing wrapper scripts.

VCL CONFIGURATION

Keys are defined in VCL, by writing a 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 a std.log() entry prefixed with "vcs-unique-id:".

EXAMPLES

VCL Configuration

Configuring the key definitions in VCL may look like this:

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

    if (obj.hits == 0) {
      std.log("vcs-key:MISS");
    }
  }

HISTORY

This document was written by Dag Haavi Finstad daghf@varnish-software.com.