Commit 88f98c0c authored by Geoff Simmons's avatar Geoff Simmons

Update documentation about the stats.

Implmentation-dependent stats are now described in an external
document.

Fix some VSC long-form documentation while we're here.
parent 67a877cc
......@@ -943,13 +943,6 @@ STATISTICS
When ``.create_stats()`` is invoked for a set object, statistics are
created that can be viewed with a tool like varnishstat(1).
*NOTE*: except for ``elements``, the stats refer to properties of a
set object's internal data structure, and hence depend on the internal
implementation. The implementation may be changed in any new version
of the VMOD, and hence the stats may change. If you install a new
version, check the new version of the present document to see if there
are new or different statistics.
The stats have the following naming schema::
SELECTOR.<vcl>.<object>.<stat>
......@@ -960,7 +953,10 @@ of the ``myset`` object in the VCL instance ``boot`` is named::
SELECTOR.boot.myset.elements
The VMOD currently provides the following statistics:
The statistics describe properties of the set, and their values are
constant, never changing during the lifetime of the VCL instance.
Statistics provided by the VMOD include:
* ``elements``: the number of elements in the set (added via
``.add()``)
......@@ -969,27 +965,15 @@ The VMOD currently provides the following statistics:
the lengths of all of the strings, including their terminating null
bytes
* ``nodes``: the total number of nodes in the internal data structure
* ``nodesz``: the size of a node in the internal data structure
(bytes)
* ``leaves``: the number of leaf nodes in the internal data structure.
There may be fewer leaf nodes than elements of the set, if the set
contains common prefixes.
* ``dmin``: the minimum depth of a terminating node in the internal
data structure; that is, a node at which a matching string may be
found (not necessarily a leaf node, if the set has common prefixes)
* ``dmax``: the maximum depth of a terminating node in the internal
data structure
* ``minlen``: the length of the shortest string in the set
* ``davg``: the average depth of a terminating node in the internal
data structure, rounded to the nearest integer
* ``maxlen``: the length of the shortest string in the set
The values of the stats are constant; they do not change during the
lifetime of the VCL instance.
The remaining stats refer to properties of a set object's internal
data structures, and depend on the internal implementation. The
implementation may be changed in any new version of the VMOD, and
hence the stats may change. These are described further in an external
document (see `STATISTICS <STATISTICS.md>`_ in the source repository).
The stats for a VCL instance are removed from view when the instance is
set to the cold state, and become visible again when it set to the warm
......
# Implementation-dependent statistics for VMOD selector
As documented in [README](README.rst), VMOD selector may optionally
generate statistics that can be viewed with a tool like varnishstat(1)
(if the method `.create_stats()` is invoked in `vcl_init`). These
describe properties of the set object, and many of them refer to
properties of the object's internal data structures, dependent on the
internal implementation. These are described in the following.
Since they depend on the implementation, these stats may change in any
new version of the VMOD. This will be not considered a breaking
change. Consult the version of this document corresponding to your
version of the VMOD for current information about the statistics.
All of the stats values are constant, never changing during the
lifetime of the VCL instance.
As noted in [README](README.rst), the stats as displayed by
Varnish tools have this naming schema:
```
SELECTOR.<vcl>.<object>.<stat>
```
... where `<vcl>` is the VCL instance name, `<object>` is the object
name, and `<stat>` is the statistic. The names documented in the
following appear in the `<stat>` position.
## Hash stats
For the `.match()` operation, the VMOD constructs data structures for
perfect hashing based on universal hashing. For hash lookup, the VMOD
initially computes a primary hash function. For hash buckets at which
strings in the set are known to collide, the VMOD computes a secondary
hash, specific to each such bucket and limited to the colliding
strings. The secondary hashes never collide.
Stat names concerning the hashes are prefixed with `hash_`:
* `hash_buckets`: the number of buckets in the primary hash table.
This is the smallest power of two larger than the number of strings
in the set.
* `hash_collisions`: the number of values in the primary hash to which
more than one string in the set is hashed
* `hash_keylen`: the length of the primary hash key vector, in blocks
of 8 bytes
* `hash_h2_buckets_min`: the minimum number of buckets in a secondary
hash table. Similar to the primary hash, the number of buckets in
each secondary hash is the smallest power of two larger than the
number of strings represented by the hash.
* `hash_h2_buckets_max`: the maximum number of buckets in a secondary
hash table
* `hash_h2_buckets_avg`: the average number of buckets in a secondary
hash table, rounded to the nearest integer
* `hash_h2_strings_min`: the minimum number of strings in a secondary
hash table
* `hash_h2_strings_max`: the maximum number of strings in a secondary
hash table
* `hash_h2_strings_avg`: the average number of strings in a secondary
hash table, rounded to the nearest integer
* `hash_h2_klen_min`: the minimum key vector length in a secondary
hash table, in blocks of 8 bytes
* `hash_h2_klen_max`: the maximum key vector length in a secondary
hash table
* `hash_h2_klen_avg`: the average key vector length in a secondary
hash table, rounded to the nearest integer
## Trie stats
For the `.hasprefix()` operation, the VMOD constructs a "quadbit
patricia trie" -- a trie for which each character is examined a nibble
at a time, and for which each node may branch up to 16 ways to the
next nodes.
Stat names concerning tries are prefixed with `trie_`:
* `trie_nodes`: the total number of nodes in the trie
* `trie_nodesz`: the size of a trie node in bytes
* `trie_leaves`: the number of leaf nodes in the trie
* `trie_depth_min`: the minimum depth of a terminating node in the
trie -- a node at which an element of the set may be found. Note
that a terminating node may be a non-leaf node, if there are strings
that are prefixes of other strings in the same set.
* `trie_depth_max`: the maximum depth of a terminating node in the
trie
* `trie_depth_avg`: the average depth of a terminating node in the
trie, rounded to the nearest integer
* `trie_fanout_min`: the minimum number of branches at a non-leaf trie
node. Fanout is always in the range 1 to 16.
* `trie_fanout_max`: the maximum number of branches at a non-leaf trie
node
* `trie_fanout_avg`: the average number of branches at a non-leaf trie
node, rounded to the nearest integer
......@@ -60,7 +60,7 @@
:level: debug
:oneliner: Primary hash key vector length
Length of the hash key vectors, in blocks of 8 bytes
Length of the primary hash key vector, in blocks of 8 bytes
.. varnish_vsc:: hash_h2_buckets_min
:type: gauge
......@@ -123,7 +123,7 @@
.. varnish_vsc:: hash_h2_klen_avg
:type: gauge
:level: debug
:oneliner: Average secondary hash strings
:oneliner: Average secondary hash key vector length
Average key vector length for secondary hashes, rounded to the
nearest integer
......
......@@ -831,13 +831,6 @@ STATISTICS
When ``.create_stats()`` is invoked for a set object, statistics are
created that can be viewed with a tool like varnishstat(1).
*NOTE*: except for ``elements``, the stats refer to properties of a
set object's internal data structure, and hence depend on the internal
implementation. The implementation may be changed in any new version
of the VMOD, and hence the stats may change. If you install a new
version, check the new version of the present document to see if there
are new or different statistics.
The stats have the following naming schema::
SELECTOR.<vcl>.<object>.<stat>
......@@ -848,7 +841,10 @@ of the ``myset`` object in the VCL instance ``boot`` is named::
SELECTOR.boot.myset.elements
The VMOD currently provides the following statistics:
The statistics describe properties of the set, and their values are
constant, never changing during the lifetime of the VCL instance.
Statistics provided by the VMOD include:
* ``elements``: the number of elements in the set (added via
``.add()``)
......@@ -857,27 +853,15 @@ The VMOD currently provides the following statistics:
the lengths of all of the strings, including their terminating null
bytes
* ``nodes``: the total number of nodes in the internal data structure
* ``nodesz``: the size of a node in the internal data structure
(bytes)
* ``leaves``: the number of leaf nodes in the internal data structure.
There may be fewer leaf nodes than elements of the set, if the set
contains common prefixes.
* ``dmin``: the minimum depth of a terminating node in the internal
data structure; that is, a node at which a matching string may be
found (not necessarily a leaf node, if the set has common prefixes)
* ``dmax``: the maximum depth of a terminating node in the internal
data structure
* ``minlen``: the length of the shortest string in the set
* ``davg``: the average depth of a terminating node in the internal
data structure, rounded to the nearest integer
* ``maxlen``: the length of the shortest string in the set
The values of the stats are constant; they do not change during the
lifetime of the VCL instance.
The remaining stats refer to properties of a set object's internal
data structures, and depend on the internal implementation. The
implementation may be changed in any new version of the VMOD, and
hence the stats may change. These are described further in an external
document (see `STATISTICS <STATISTICS.md>`_ in the source repository).
The stats for a VCL instance are removed from view when the instance is
set to the cold state, and become visible again when it set to the warm
......
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