.. role:: ref(emphasis)

.. _varnishstat(1):

===========
varnishstat
===========

------------------------
Varnish Cache statistics
------------------------

:Manual section: 1

SYNOPSIS
========

varnishstat [-1] [-x] [-j] [-f field] [-l] [-n varnish_name] [-N filename] [-t seconds|<off>] [-V]

.. TODO: autogenerate this synopsis like the others.

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

The varnishstat utility displays statistics from a running varnishd(1) instance.

OPTIONS
=======

The following options are available:

-1
	Instead of presenting a continuously updated display, print
	the statistics to stdout.

-f
	Field inclusion glob.  Use backslash to escape characters. If
	the argument starts with '^' it is used as an exclusive glob.
	Multiple -f arguments may be given. Inclusive globs are
	accumulative and are run before exclusive ones.

-l
	Lists the available fields to use with the -f option.

-n
	Specifies the name of the varnishd instance to get logs from.
	If -n is not specified, the host name is used.

-N
	Specify a the filename of a stale VSM instance. When using
        this option the abandonment checking is disabled.

-t seconds|<off>
	Timeout before returning error on initial VSM connection.  If
	set the VSM connection is retried every 0.5 seconds for this
	any 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
	Display the version number and exit.

-x
	Displays the result as XML.

-j
	Displays the result as JSON.

CURSES MODE
===========

When neither -1, -j or -x options are given, the application starts up
in curses mode. This shows a continuously updated view of the counter
values, along with their description.

The top area shows process uptime information.

The center area shows a list of counter values.

The bottom area shows the description of the currently selected
counter.

Columns
-------

The following columns are displayed, from left to right:

Name
	The name of the counter

Current
	The current value of the counter.

Change
	The average per second change over the last update interval.

Average
	The average value of this counter over the runtime of the
	Varnish daemon, or a period if the counter can't be averaged.

Avg_10
	The moving average over the last 10 update intervals.

Avg_100
	The moving average over the last 100 update intervals.

Avg_1000
	The moving average over the last 1000 update intervals.

Key bindings
------------

The following keys control the interactive display:

<UP>
	Navigate the counter list one line up.

<DOWN>
	Navigate the counter list one line down.

<PAGEUP> or <b>
	Navigate the counter list one page up.

<PAGEDOWN> or <SPACE>
	Navigate the counter list one page down.

<d>
	Toggle between showing and hiding unseen counters. Unseen
	counters are those that has been zero for the entire runtime
	of varnishstat. Defaults to hide unseen counters.

<e>
	Toggle scaling of values.

<g>
	Go to the top of the counter list.

<G>
	Go to the bottom of the counter list.

<v>
	Cycle through the verbosity levels. Defaults to only showing
	informational counters.

<q>
	Quit.

<CTRL+T>
	Sample now.

XML Output
==========

When using the -x option, the output is::

  <varnishstat timestamp="YYYY-MM-DDTHH:mm:SS">
    <stat>
      <type>FIELD TYPE</type>
      <ident>FIELD IDENT</ident>
      <name>FIELD NAME</name>
      <value>FIELD VALUE</value>
      <flag>FIELD SEMANTICS</flag>
      <format>FIELD DISPLAY FORMAT</format>
      <description>FIELD DESCRIPTION</description>
    </stat>
    [..]
  </varnishstat>

JSON OUTPUT
===========

With -j the output format is::

  {
    "timestamp": "YYYY-MM-DDTHH:mm:SS",
    "FIELD NAME": {
      "description": "FIELD DESCRIPTION",
      "type": "FIELD TYPE", "ident": "FIELD IDENT", "flag": "FIELD SEMANTICS", "format": "FIELD DISPLAY FORMAT",
      "value": FIELD VALUE
    },
    "FIELD2 NAME": {
      "description": "FIELD2 DESCRIPTION",
      "type": "FIELD2 TYPE", "ident": "FIELD2 IDENT", "flag": "FIELD2 SEMANTICS", "format": "FIELD2 DISPLAY FORMAT",
      "value": FIELD2 VALUE
    },
    [..]
  }


Type and ident are optional.  Timestamp is the time when the report was
generated by varnishstat.

Repeated output with -1, -x or -j will have a single empty line (\\n)
between each block of output.


SEE ALSO
========

* :ref:`varnishd(1)`
* :ref:`varnishhist(1)`
* :ref:`varnishlog(1)`
* :ref:`varnishncsa(1)`
* :ref:`varnishtop(1)`
* curses(3)
* :ref:`varnish-counters(7)`


AUTHORS
=======

This manual page was written by Dag-Erling Smørgrav, Per Buer,
Lasse Karstensen and Martin Blix Grydeland.