Skip to content

L
libvdp-pesi
Commit 9786b2da authored by Geoff Simmons's avatar Geoff Simmons
Browse files
Options

Docs WIP

parent 1f9e68dd
Hide whitespace changes
Inline Side-by-side
Showing with 276 additions and 20 deletions
README.rst
View file @ 9786b2da
......@@ -603,7 +603,7 @@ manage tasks being run in different threads. The VDP uses Varnish's
mechanisms for implementing locks, so they can be observed with
``LCK.*`` statistics.
To summarize, the VDP makes use of these resources:
To summarize, the VDP makes use of the following resources:
* Transient storage
......@@ -615,17 +615,140 @@ To summarize, the VDP makes use of these resources:
* locks
XXX TBfinished ...
These resources are configured as follows:
.. _Storage Backend: https://varnish-cache.org/docs/trunk/reference/varnishd.html#storage-backend
.. _Storage backends: https://varnish-cache.org/docs/trunk/users-guide/storage-backends.html
.. _Varnish User's Guide: https://varnish-cache.org/docs/trunk/users-guide/index.html
* A maximum size for Transient storage can be set with the ``-s``
command-line option for varnishd, using the name ``Transient`` for
the storage backend (see `Storage Backend`_ in `varnishd(1)`_, and
`Storage backends`_ in the `Varnish User's Guide`_). If no storage
backend with the name ``Transient`` is specified, then Varnish uses
unlimited malloc storage for Transient. Set ``-sTransient`` to set
an upper bound.
Example::
varnishd -sTransient=malloc,500m
* Thread pools are configured with the varnishd parameters
``thread_pools``, ``thread_pool_min`` and ``thread_pool_max``, see
`varnishd(1)`_.
Example::
varnishd -p thread_pools=4 -p thread_pool_min=500 -p thread_pool_max=1000
* Client workspace is configured with the varnishd parameter
``workspace_client``, see `varnishd(1)`_. The VDP's use of client
workspace can be configured in part by using the
``workspace_prealloc()`` function described above.
Example::
varnishd -p workspace_client=128k
# See also the examples for pesi.workspace_prealloc() above.
* The VDP's memory pool is configured with the ``pool()`` function
described above.
Statistics counters that are relevant to the resource usage of the VDP
are:
.. _varnish-counters(7): https://varnish-cache.org/docs/trunk/reference/varnish-counters.html
.. _SMA: https://varnish-cache.org/docs/trunk/reference/varnish-counters.html#sma-malloc-stevedore-counters
.. _LCK: https://varnish-cache.org/docs/trunk/reference/varnish-counters.html#lck-lock-counters
.. _MEMPOOL: https://varnish-cache.org/docs/trunk/reference/varnish-counters.html#mempool-memory-pool-counters
* ``SMA.Transient.*`` for the use of Transient storage, see the `SMA`_
section in `varnish-counters(7)`_.
* ``MAIN.threads`` shows the current number of threads in all pools.
``MAIN.threads_limited`` shows the number of times threads were
requested from the pools, but the limit imposed by
``thread_pool_max`` was reached. See `varnish-counters(7)`_.
You may also want to monitor ``MAIN.thread_queue_len``. This is the
length of the queue for sessions that are waiting for a thread so
that Varnish can accept new client connections -- a sign that thread
pools may be too small.
* ``MAIN.ws_client_overflow`` shows the number of times client
workspace was exhausted (see `varnish-counters(7)`_). Workspace
overflow will also cause ``pesi.activate()`` to invoke VCL failure
(see `ERRORS`_).
* The VDP adds custom counters ``LCK.pesi.buf.*`` and
``LCK.pesi.tasks.*``, so that its locks may be monitored; see the
`LCK`_ section in `varnish-counters(7)`_.
Varnish since version 6.2.0 has the ``lck`` flag for the varnishd
parameter ``debug``. When the flag is set, the
``LCK.pesi.*.dbg_busy`` counters are incremented when there is lock
contention, see `varnishd(1)`_.
Example::
varnishd -p debug=+lck
* The VDP also adds the ``MEMPOOL.pesi.*`` counters, to monitor the
memory pool described in the documentation for ``pool()`` above.
See the `MEMPOOL`_ section in `varnish-counters(7)`_.
* The VDP adds another counter ``PESI.no_thread``, which is
incremented when ``set(thread, false)`` has been set as described
above, and an ESI subrequest had to be processed in serial (in the
same thread as for the including request), because no thread was
available from the thread pools.
Considerations about tuning the configuration and interpreting the
statistics are beyond the scope of this manual. For a deeper
discussion, see $EXTERNAL_DOCUMENT.
LIMITATIONS
===========
XXX @geoff pls reword
Because ReqAcct includes chunk headers, depending on the order of
events and whether or not we use (partial) sequential delivery (for
example, when no threads are available), ReqAcct adds n x 8 to the net
data size.
As emphasized above, ``pesi.activate()`` must be called at all ESI
levels if it is called at any ESI level (and equivalently, if ``pesi``
is added by hand to ``resp.filters``, it must be present in
``resp.filters`` at all ESI levels). This is similar to the fact that
serial ESI processing in standard Varnish cannot be disabled in the
"middle" of an ESI tree. If ``resp.do_esi`` is set to ``false`` (in
VCL 4.1) after ESI processing has already begun, Varnish knows to
ignore it, and ESI processing continues. But the pesi VDP is unable to
check for this condition -- it can only operate at all if
``activate()`` has been called (or ``pesi`` is present in
``resp.filters``).
If VDP pesi has been activated at ESI level 0 but not at another
level, Varnish is likely to infer that standard serial ESI processing
should be invoked for the subrequest. The standard ESI VDP and the
pesi VDP are not compatible with one another, so that this situation
is very likely to lead to a Varnish panic. There is nothing we can do
to prevent that, other than urgently advise users to activate VDP pesi
at all ESI levels, or not at all.
.. _vsl(7): https://varnish-cache.org/docs/trunk/reference/vsl.html
The size of the response body as reported by Varnish log records with
the ``ReqAcct`` tag (see `vsl(7)`_) may be slightly different for
different deliveries of the same ESI tree, even though the responses
as viewed by a client are identical. This has to do with the way
fragments in the response are transmitted on the wire to clients --
chunked encoding for HTTP/1, and sequences of DATA frames for
HTTP/2. The overhead for these transmission methods is included in the
accounting of ``ReqAcct``. The "chunking" of the response may differ
at different times, depending on the order of events, and on whether
or not we use (partial) sequential delivery (for example, when no
threads are available).
REQUIREMENTS
============
......@@ -636,6 +759,12 @@ This version of the VDP requires the Varnish master branch since
commit `bdf2f63`_. See the source repository for versions that are
compatible with other versions of Varnish (since 6.2.0).
All versions of the VDP require strict ABI compatibility with Varnish,
meaning that it must run against the same build version of Varnish as
the version against which the VDP was built. This means that the
"commit id" portion of the Varnish version string (the SHA1 hash) must
be the same at runtime as at build time.
INSTALLATION
============
......@@ -646,11 +775,10 @@ SEE ALSO
.. _Content composition with Edge Side Includes: https://varnish-cache.org/docs/trunk/users-guide/esi.html
.. _Varnish User's Guide: https://varnish-cache.org/docs/trunk/users-guide/index.html
* `varnishd(1)`_
* `vcl(7)`_
* `varnishstat(1)`_
* `varnish-counters(7)`_
* `varnishadm(1)`_
* `Content composition with Edge Side Includes`_ in the `Varnish User's Guide`_
......
src/vdp_pesi.vcc
View file @ 9786b2da
......@@ -580,7 +580,7 @@ manage tasks being run in different threads. The VDP uses Varnish's
mechanisms for implementing locks, so they can be observed with
``LCK.*`` statistics.
To summarize, the VDP makes use of these resources:
To summarize, the VDP makes use of the following resources:
* Transient storage
......@@ -592,17 +592,140 @@ To summarize, the VDP makes use of these resources:
* locks
XXX TBfinished ...
These resources are configured as follows:
.. _Storage Backend: https://varnish-cache.org/docs/trunk/reference/varnishd.html#storage-backend
.. _Storage backends: https://varnish-cache.org/docs/trunk/users-guide/storage-backends.html
.. _Varnish User's Guide: https://varnish-cache.org/docs/trunk/users-guide/index.html
* A maximum size for Transient storage can be set with the ``-s``
command-line option for varnishd, using the name ``Transient`` for
the storage backend (see `Storage Backend`_ in `varnishd(1)`_, and
`Storage backends`_ in the `Varnish User's Guide`_). If no storage
backend with the name ``Transient`` is specified, then Varnish uses
unlimited malloc storage for Transient. Set ``-sTransient`` to set
an upper bound.
Example::
varnishd -sTransient=malloc,500m
* Thread pools are configured with the varnishd parameters
``thread_pools``, ``thread_pool_min`` and ``thread_pool_max``, see
`varnishd(1)`_.
Example::
varnishd -p thread_pools=4 -p thread_pool_min=500 -p thread_pool_max=1000
* Client workspace is configured with the varnishd parameter
``workspace_client``, see `varnishd(1)`_. The VDP's use of client
workspace can be configured in part by using the
``workspace_prealloc()`` function described above.
Example::
varnishd -p workspace_client=128k
# See also the examples for pesi.workspace_prealloc() above.
* The VDP's memory pool is configured with the ``pool()`` function
described above.
Statistics counters that are relevant to the resource usage of the VDP
are:
.. _varnish-counters(7): https://varnish-cache.org/docs/trunk/reference/varnish-counters.html
.. _SMA: https://varnish-cache.org/docs/trunk/reference/varnish-counters.html#sma-malloc-stevedore-counters
.. _LCK: https://varnish-cache.org/docs/trunk/reference/varnish-counters.html#lck-lock-counters
.. _MEMPOOL: https://varnish-cache.org/docs/trunk/reference/varnish-counters.html#mempool-memory-pool-counters
* ``SMA.Transient.*`` for the use of Transient storage, see the `SMA`_
section in `varnish-counters(7)`_.
* ``MAIN.threads`` shows the current number of threads in all pools.
``MAIN.threads_limited`` shows the number of times threads were
requested from the pools, but the limit imposed by
``thread_pool_max`` was reached. See `varnish-counters(7)`_.
You may also want to monitor ``MAIN.thread_queue_len``. This is the
length of the queue for sessions that are waiting for a thread so
that Varnish can accept new client connections -- a sign that thread
pools may be too small.
* ``MAIN.ws_client_overflow`` shows the number of times client
workspace was exhausted (see `varnish-counters(7)`_). Workspace
overflow will also cause ``pesi.activate()`` to invoke VCL failure
(see `ERRORS`_).
* The VDP adds custom counters ``LCK.pesi.buf.*`` and
``LCK.pesi.tasks.*``, so that its locks may be monitored; see the
`LCK`_ section in `varnish-counters(7)`_.
Varnish since version 6.2.0 has the ``lck`` flag for the varnishd
parameter ``debug``. When the flag is set, the
``LCK.pesi.*.dbg_busy`` counters are incremented when there is lock
contention, see `varnishd(1)`_.
Example::
varnishd -p debug=+lck
* The VDP also adds the ``MEMPOOL.pesi.*`` counters, to monitor the
memory pool described in the documentation for ``pool()`` above.
See the `MEMPOOL`_ section in `varnish-counters(7)`_.
* The VDP adds another counter ``PESI.no_thread``, which is
incremented when ``set(thread, false)`` has been set as described
above, and an ESI subrequest had to be processed in serial (in the
same thread as for the including request), because no thread was
available from the thread pools.
Considerations about tuning the configuration and interpreting the
statistics are beyond the scope of this manual. For a deeper
discussion, see $EXTERNAL_DOCUMENT.
LIMITATIONS
===========
XXX @geoff pls reword
Because ReqAcct includes chunk headers, depending on the order of
events and whether or not we use (partial) sequential delivery (for
example, when no threads are available), ReqAcct adds n x 8 to the net
data size.
As emphasized above, ``pesi.activate()`` must be called at all ESI
levels if it is called at any ESI level (and equivalently, if ``pesi``
is added by hand to ``resp.filters``, it must be present in
``resp.filters`` at all ESI levels). This is similar to the fact that
serial ESI processing in standard Varnish cannot be disabled in the
"middle" of an ESI tree. If ``resp.do_esi`` is set to ``false`` (in
VCL 4.1) after ESI processing has already begun, Varnish knows to
ignore it, and ESI processing continues. But the pesi VDP is unable to
check for this condition -- it can only operate at all if
``activate()`` has been called (or ``pesi`` is present in
``resp.filters``).
If VDP pesi has been activated at ESI level 0 but not at another
level, Varnish is likely to infer that standard serial ESI processing
should be invoked for the subrequest. The standard ESI VDP and the
pesi VDP are not compatible with one another, so that this situation
is very likely to lead to a Varnish panic. There is nothing we can do
to prevent that, other than urgently advise users to activate VDP pesi
at all ESI levels, or not at all.
.. _vsl(7): https://varnish-cache.org/docs/trunk/reference/vsl.html
The size of the response body as reported by Varnish log records with
the ``ReqAcct`` tag (see `vsl(7)`_) may be slightly different for
different deliveries of the same ESI tree, even though the responses
as viewed by a client are identical. This has to do with the way
fragments in the response are transmitted on the wire to clients --
chunked encoding for HTTP/1, and sequences of DATA frames for
HTTP/2. The overhead for these transmission methods is included in the
accounting of ``ReqAcct``. The "chunking" of the response may differ
at different times, depending on the order of events, and on whether
or not we use (partial) sequential delivery (for example, when no
threads are available).
REQUIREMENTS
============
......@@ -613,6 +736,12 @@ This version of the VDP requires the Varnish master branch since
commit `bdf2f63`_. See the source repository for versions that are
compatible with other versions of Varnish (since 6.2.0).
All versions of the VDP require strict ABI compatibility with Varnish,
meaning that it must run against the same build version of Varnish as
the version against which the VDP was built. This means that the
"commit id" portion of the Varnish version string (the SHA1 hash) must
be the same at runtime as at build time.
INSTALLATION
============
......@@ -623,11 +752,10 @@ SEE ALSO
.. _Content composition with Edge Side Includes: https://varnish-cache.org/docs/trunk/users-guide/esi.html
.. _Varnish User's Guide: https://varnish-cache.org/docs/trunk/users-guide/index.html
* `varnishd(1)`_
* `vcl(7)`_
* `varnishstat(1)`_
* `varnish-counters(7)`_
* `varnishadm(1)`_
* `Content composition with Edge Side Includes`_ in the `Varnish User's Guide`_
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment