Add the STATISTICS docs.

README.rst

@@ -407,7 +407,55 @@ Example::
 STATISTICS
 ==========
 
-XXX ...
+The VFP creates counters in the ``BROTLI.*`` namespace, which can be
+read and monitored with a tool like ``varnishstat(1)``, or any other
+client of the Varnish statistics API.
+
+Counters for the built-in filters ``"br"`` and ``"unbr"`` are always
+created, with names of the form ``BROTLI.br.*`` and
+``BROTLI.unbr.*``. If you use the ``encoder`` and/or ``decoder``
+objects to create filters with custom parameters, you may optionally
+use the ``.create_stats()`` method for either object type to create
+counters for the custom filters. If so, then these counters have names
+of the form::
+
+  BROTLI.<vcl_name>.<filter_name>.*
+
+... where ``<vcl_name>`` is the name of the VCL configuration, and
+``<filter_name>`` is the name of the filter as used in
+``beresp.filters``.
+
+The stats are:
+
+* ``ops``: total number of de-/compression operations. Always incremented
+  even when the filter does not make any changes, for example when a
+  compression filter finds that a backend response already has a
+  ``Content-Encoding`` header.
+
+* ``in``: total number of input bytes processed by the filter
+
+* ``out``: total number of ouput bytes produced by the filter
+
+All three stats are counters, meaning that they are always monotonic
+increasing, except when the Varnish worker process restarts and they
+are reset to 0.
+
+So these stats are always created when the VFP is imported:
+
+* ``BROTLI.br.ops``
+* ``BROTLI.br.in``
+* ``BROTLI.br.out``
+* ``BROTLI.unbr.ops``
+* ``BROTLI.unbr.in``
+* ``BROTLI.unbr.out``
+
+And stats for custom filters are also created if you so choose.
+
+The work of the VFP in individual request/response transactions can
+also be monitored in the Varnish log, recorded with the ``VfpAcct``
+tag (see ``vsl(7)``). By default, ``VfpAcct`` is not written to the
+log; to see it, set the ``varnishd`` parameter ``vsl_mask`` to
+``+VfpAcct``.
 
 ERRORS
 ======
@@ -435,6 +483,7 @@ SEE ALSO
 * varnishd(1)
 * vcl(7)
 * varnishstat(1)
+* vsl(7)
 * VMOD source repository: https://code.uplex.de/uplex-varnish/libvfp-brotli
 * brotli library repository: https://github.com/google/brotli
 * RFC 7932 (brotli specification): https://tools.ietf.org/html/rfc7932

src/vfp_brotli.vcc

@@ -371,7 +371,55 @@ Example::
 STATISTICS
 ==========
 
-XXX ...
+The VFP creates counters in the ``BROTLI.*`` namespace, which can be
+read and monitored with a tool like ``varnishstat(1)``, or any other
+client of the Varnish statistics API.
+
+Counters for the built-in filters ``"br"`` and ``"unbr"`` are always
+created, with names of the form ``BROTLI.br.*`` and
+``BROTLI.unbr.*``. If you use the ``encoder`` and/or ``decoder``
+objects to create filters with custom parameters, you may optionally
+use the ``.create_stats()`` method for either object type to create
+counters for the custom filters. If so, then these counters have names
+of the form::
+
+  BROTLI.<vcl_name>.<filter_name>.*
+
+... where ``<vcl_name>`` is the name of the VCL configuration, and
+``<filter_name>`` is the name of the filter as used in
+``beresp.filters``.
+
+The stats are:
+
+* ``ops``: total number of de-/compression operations. Always incremented
+  even when the filter does not make any changes, for example when a
+  compression filter finds that a backend response already has a
+  ``Content-Encoding`` header.
+
+* ``in``: total number of input bytes processed by the filter
+
+* ``out``: total number of ouput bytes produced by the filter
+
+All three stats are counters, meaning that they are always monotonic
+increasing, except when the Varnish worker process restarts and they
+are reset to 0.
+
+So these stats are always created when the VFP is imported:
+
+* ``BROTLI.br.ops``
+* ``BROTLI.br.in``
+* ``BROTLI.br.out``
+* ``BROTLI.unbr.ops``
+* ``BROTLI.unbr.in``
+* ``BROTLI.unbr.out``
+
+And stats for custom filters are also created if you so choose.
+
+The work of the VFP in individual request/response transactions can
+also be monitored in the Varnish log, recorded with the ``VfpAcct``
+tag (see ``vsl(7)``). By default, ``VfpAcct`` is not written to the
+log; to see it, set the ``varnishd`` parameter ``vsl_mask`` to
+``+VfpAcct``.
 
 ERRORS
 ======
@@ -399,6 +447,7 @@ SEE ALSO
 * varnishd(1)
 * vcl(7)
 * varnishstat(1)
+* vsl(7)
 * VMOD source repository: https://code.uplex.de/uplex-varnish/libvfp-brotli
 * brotli library repository: https://github.com/google/brotli
 * RFC 7932 (brotli specification): https://tools.ietf.org/html/rfc7932