.. role:: ref(emphasis)

.. _varnishncsa(1):

===========
varnishncsa
===========

---------------------------------------------------------
Display Varnish logs in Apache / NCSA combined log format
---------------------------------------------------------

:Manual section: 1

SYNOPSIS
========

.. include:: ../include/varnishncsa_synopsis.rst
varnishncsa |synopsis|

DESCRIPTION
===========

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:

.. include:: ../include/varnishncsa_options.rst

MODES
=====

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.

FORMAT
======

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:

%b
  In client mode, size of response in bytes, excluding HTTP headers.
  In backend mode, the number of bytes received from the backend,
  excluding HTTP headers.  In CLF format, i.e. a '-' rather than a 0
  when no bytes are sent.

%D
  In client mode, time taken to serve the request, in microseconds.
  In backend mode, time from the request was sent to the entire body
  had been received.

%H
  The request protocol. Defaults to HTTP/1.0 if not known.

%h
  Remote host. Defaults to '-' if not known.  In backend mode this is
  the IP of the backend server.

%I
  In client mode, total bytes received from client.  In backend mode,
  total bytes sent to the backend.

%{X}i
  The contents of request header X.

%l
  Remote logname. Always '-'.

%m
  Request method. Defaults to '-' if not known.

%{X}o
  The contents of response header X.

%O
  In client mode, total bytes sent to client.  In backend mode, total
  bytes received from the backend.

%q
  The query string. Defaults to an empty string if not present.

%r
  The first line of the request. Synthesized from other fields, so it
  may not be the request verbatim.

%s
  Status sent to the client.  In backend mode, status received from
  the backend.

%t
  In client mode, time when the request was received, in HTTP
  date/time format.  In backend mode, time when the request was sent.

%{X}t
  In client mode, time when the request was received, in the format
  specified by X.  In backend mode, time when the request was sent.
  The time specification format is the same as for strftime(3).

%T
  In client mode, time taken to serve the request, in seconds.  In
  backend mode, time from the request was sent to the entire body had
  been received.

%U
  The request URL without the query string. Defaults to '-' if not
  known.

%u
  Remote user from auth.

%{X}x
  Extended variables.  Supported variables are:

  Varnish:time_firstbyte
    Time from when the request processing starts until the first byte
    is sent to the client.  For backend mode: Time from the request was
    sent to the backend to the entire header had been received.

  Varnish:hitmiss
    Whether the request was a cache hit or miss. Pipe and pass are
    considered misses.

  Varnish:handling
    How the request was handled, whether it was a cache hit, miss,
    pass, pipe or synth.

  Varnish:side
    Backend or client side. One of two values, 'b' or 'c', depending
    on where the request was made. In pure backend or client mode,
    this field will be constant.

  Varnish:vxid
    The VXID of the varnish transaction.

  VCL_Log:key
    Output value set by std.log("key:value") in VCL.

  VSL:tag or VSL:tag[field]
    The value of the VSL entry for the given tag.  If field is specified,
    only the selected part is shown.  Defaults to '-' when the tag is not
    seen, or when the field is out of bounds.  If a tag appears several
    times in a single transaction, only the first occurrence is used.

SIGNALS
=======

SIGHUP
  Rotate the log file (see -w option)

SIGUSR1
  Flush any outstanding transactions

EXAMPLE
=======

Log the second field of the Begin tag, corresponding to the VXID of the
parent transaction::

  varnishncsa -F "%{VSL:Begin[2]}x"

SEE ALSO
========

:ref:`varnishd(1)`
:ref:`varnishlog(1)`
:ref:`varnishstat(1)`
:ref:`vsl(7)`

HISTORY
=======

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.


COPYRIGHT
=========

This document is licensed under the same licence as Varnish
itself. See LICENCE for details.

* Copyright (c) 2006 Verdens Gang AS
* Copyright (c) 2006-2016 Varnish Software AS
