add a "Reading the varnishlog" section to Tips & Tricks

R1/source/tips/index.rst

@@ -23,3 +23,5 @@ errors. The :ref:`HowTo <contribdoc>` section will help you get started.
 .. toctree::
    contribdoc/index
    vcl/index
+   varnishlog/index
+

R1/source/tips/varnishlog/fetcherror.rst

+.. _fetcherror:
+
+Backend fetch failures and the FetchError tag
+=============================================
+
+*Why am I getting a ... Backend Fetch Error? ... 503 response code?
+... Guru Meditation?*
+
+**Always look for the FetchError tag in logs of backend transactions.**
+
+When a backend fetch encounters a problem, a log message describing
+the error is saved using the ``FetchError`` tag::
+
+  $ varnishlog -b -q 'FetchError'
+  *   << BeReq    >> 4711 
+  -   Begin          bereq 5180 pass
+  -   Timestamp      Start: 1466083875.265667 0.000000 0.000000
+  -   BereqMethod    GET
+  -   BereqURL       /foo/bar/baz
+  [...]
+  -   FetchError     http first read error: EOF
+  [...]
+  -   End            
+
+Some common contents of a ``FetchError`` line are:
+
+* ``http first read error: EOF``: Usually this indicates a first byte
+  timeout. In less common cases, the backend may have closed the
+  connection before the first byte of the response could be read.
+* ``http read error: EOF``: Usually a between-bytes timeout; rarely, a
+  backend connection while the response is being read.
+* ``no backend connection``: This may mean that the backend is
+  unhealthy (or all of the backends in a director are unhealthy), or
+  that the connection timeout expired. In the latter case (connection
+  timeout), the backend fetch timestamps will show that about exactly
+  as much time expired as is defined for ``connect_timeout``. In the
+  former case (unhealthy backends), Varnish decides immediately to
+  fail the fetch, so the timeouts show no time expired.

R1/source/tips/varnishlog/index.rst

+.. _varnishlog:
+
+Reading the varnishlog
+======================
+
+*What do the lines in varnishlog output mean?*
+
+See ``man vsl(7)`` for full documentation of the format and contents
+of Varnish log tags (or see the `online link
+<http://varnish-cache.org/docs/trunk/reference/vsl.html>`_, in this
+case for current trunk, or for your Varnish version).
+
+*How do I filter varnishlog output to make it more manageable?*
+
+`man vsl-query(7)
+<http://varnish-cache.org/docs/trunk/reference/vsl-query.html>`_ shows
+you how to use VSL queries to pick out log transactions with contents
+you specify. See also `man varnishlog(1)
+<http://varnish-cache.org/docs/trunk/reference/varnishlog.html>`_ for
+command-line options that restrict the output for each
+transaction. Some useful ones are:
+
+* ``-i``: only show log lines with certain tags
+* ``-I``: only show lines matching a list of tags and a regular expression
+* ``-x``: don't show lines with certain tags
+* ``-X``: don't show lines matching a list of tags and a regular expression
+
+Multiple options are allowed on the command line for each of these.
+  
+.. toctree::
+   fetcherror