[master] 4dc2402ae Document VSC files

Nils Goroll nils.goroll at uplex.de
Thu May 14 09:28:06 UTC 2020

commit 4dc2402ae23aa5b83fed418005d034ee4503b858
Author: Jordan Christiansen <Jordan.Christiansen at target.com>
Date:   Thu Apr 30 16:29:10 2020 -0500

    Document VSC files

diff --git a/doc/sphinx/reference/vmod.rst b/doc/sphinx/reference/vmod.rst
index faa5e374d..c48f51f13 100644
--- a/doc/sphinx/reference/vmod.rst
+++ b/doc/sphinx/reference/vmod.rst
@@ -636,3 +636,65 @@ unless they access VMOD specific global state, shared with other VCLs.
 Traffic in other VCLs which also import this VMOD, will be happening
 while housekeeping is going on.
+Statistics Counters
+Starting in Varnish 6.0, VMODs can define their own counters that appear
+in *varnishstat*.
+If you're using autotools, see the ``VARNISH_COUNTERS`` macro in
+varnish.m4 for documentation on getting your build set up.
+Counters are defined in a .vsc file. The ``VARNISH_COUNTERS`` macro
+calls *vsctool.py* to turn a *foo.vsc* file into *VSC_foo.c* and
+*VSC_foo.h* files, just like *vmodtool.py* turns *foo.vcc* into
+*vcc_foo_if.c* and *vcc_foo_if.h* files. Similarly to the VCC files, the
+generated VSC files give you a structure and functions that you can use
+in your VMOD's code to create and destroy the counters your defined. The
+*vsctool.py* tool also generates a *VSC_foo.rst* file that you can
+include in your documentation to describe the counters your VMOD has.
+The .vsc file looks like this::
+	.. varnish_vsc_begin:: xkey
+		:oneliner:	xkey Counters
+		:order:		70
+		Metrics from vmod_xkey
+	.. varnish_vsc:: g_keys
+		:type:		gauge
+		:oneliner:	Number of surrogate keys
+		Number of surrogate keys in use. Increases after a request that includes a new key in the xkey header. Decreases when a key is purged or when all cache objects associated with a key expire.
+	.. varnish_vsc_end:: xkey
+Counters can have the following parameters:
+	The type of metric this is. Can be one of ``counter``,
+	``gauge``, or ``bitmap``.
+	The type that this counter will have in the C code. This can
+	only be ``uint64_t`` and does not need to be specified.
+	The verbosity level of this counter. *varnishstat* will only
+	show counters with a higher verbosity level than the one
+	currently configured. Can be one of ``info``, ``diag``, or
+	``debug``.
+	A short, one line description of the counter.
+	I don't know what this does.
+	Can be one of ``integer``, ``bytes``, ``bitmap``, or ``duration``.
+After these parameters, a counter can have a longer description, though
+this description has to be all on one line in the .vsc file.

More information about the varnish-commit mailing list