Manual section: | 1 |
---|
varnishncsa [-a] [-b] [-c] [-C] [-d] [-D] [-F <format>] [-f <formatfile>] [-g <request|vxid>] [-h] [-L <limit>] [-n <name>] [-N <filename>] [-P <file>] [-q <query>] [-r <filename>] [-t <seconds|off>] [-V] [-w <filename>]
The varnishncsa utility reads varnishd(1) shared memory logs and presents them in the Apache / NCSA "combined" log format.
Each log line produced is based on a single Request type transaction gathered from the shared memory log. The Request transaction is then scanned for the relevant parts in order to output one log line. To filter the log lines produced, use the query language to select the applicable transactions. Non-request transactions are ignored.
The following options are available:
-a | When writing output to a file, append to it rather than overwrite it. |
-b | Log backend requests. If -c is not specified, then only backend requests will trigger log lines. |
-c | Log client requests. This is the default. If -b is specified, then -c is needed to also log client requests |
-C | Do all regular expression and string matching caseless. |
-d | Process log records at the head of the log and exit. |
-D | Daemonize. |
-F <format> | Set the output log format string. |
-f <formatfile> | |
Read output format from a file. Will read a single line from the specified file, and use that line as the format. | |
-g <request|vxid> | |
The grouping of the log records. The default is to group by vxid. | |
-h | Print program usage and exit |
-L <limit> | Sets the upper limit of incomplete transactions kept before the oldest transaction is force completed. A warning record is synthesized when this happens. This setting keeps an upper bound on the memory usage of running queries. Defaults to 1000 transactions. |
-n <name> | Specify the name of the varnishd instance to get logs from. If -n is not specified, the host name is used. |
-N <filename> | Specify the filename of a stale VSM instance. When using this option the abandonment checking is disabled. |
-P <file> | Write the process' PID to the specified file. |
-q <query> | Specifies the VSL query to use. |
-r <filename> | Read log in binary file format from this file. The file can be created with varnishlog -w filename. |
-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. |
-w <filename> | Redirect output to file. The file will be overwritten unless the -a option was specified. If the application receives a SIGHUP in daemon mode the file will be reopened allowing the old one to be rotated away. This option is required when running in daemon mode. |
The default mode of varnishncsa is "client mode". In this mode, the log will be similar to what a web server would produce in the absence of varnish. Client mode can be explicitly selected by using -c.
If the -b switch is specified, varnishncsa will operate in "backend mode". In this mode, requests generated by varnish to the backends will be logged. Unless -c is also specified, client requests received by varnish will be ignored.
When running varnishncsa in both backend and client mode, it is strongly advised to include the format specifier %{Varnish:side}x to distinguish between backend and client requests.
Client requests that results in a pipe (ie. return(pipe) in vcl), will not generate logging in backend mode. This is because varnish is not generating requests, but blindly passes on bytes in both directions. However, a varnishncsa instance running in normal mode can see this case by using the formatter %{Varnish:handling}x, which will be 'pipe'.
In backend mode, some of the fields in the format string get different meanings. Most notably, the byte counting formatters (%b, %I, %O) considers varnish to be the client.
It is possible to keep two varnishncsa instances running, one in backend mode, and one in client mode, logging to different files.
Specify the log format to use. If no format is specified the default log format is used:
%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-agent}i"
Escape sequences \n and \t are supported.
Supported formatters are:
Extended variables. Supported variables are:
Log the second field of the Begin tag, corresponding to the VXID of the parent transaction:
varnishncsa -F "%{VSL:Begin[2]}x"
The varnishncsa utility was developed by Poul-Henning Kamp in cooperation with Verdens Gang AS and Varnish Software AS. This manual page was initially written by Dag-Erling Smørgrav <des@des.no>, and later updated by Martin Blix Grydeland and Pål Hermunn Johansen.
This document is licensed under the same licence as Varnish itself. See LICENCE for details.