diff options
| author | Jacob McDonnell <jacob@jacobmcdonnell.com> | 2026-04-25 19:59:05 -0400 |
|---|---|---|
| committer | Jacob McDonnell <jacob@jacobmcdonnell.com> | 2026-04-25 19:59:05 -0400 |
| commit | 1f19f33e45791ea59aed048796fc68672c6723a5 (patch) | |
| tree | 54625fba89e91d1c2177801ec635e8528bba937f /static/freebsd/man3/stats.3 3.html | |
| parent | ac5e55f5f2af5b92794c2aded46c6bae85b5f5ed (diff) | |
docs: Removed Precompiled HTML
Diffstat (limited to 'static/freebsd/man3/stats.3 3.html')
| -rw-r--r-- | static/freebsd/man3/stats.3 3.html | 725 |
1 files changed, 0 insertions, 725 deletions
diff --git a/static/freebsd/man3/stats.3 3.html b/static/freebsd/man3/stats.3 3.html deleted file mode 100644 index fb277eab..00000000 --- a/static/freebsd/man3/stats.3 3.html +++ /dev/null @@ -1,725 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">STATS(3)</td> - <td class="head-vol">Library Functions Manual</td> - <td class="head-rtitle">STATS(3)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">stats</code> — <span class="Nd">statistics - gathering</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="LIBRARY"><a class="permalink" href="#LIBRARY">LIBRARY</a></h1> -<p class="Pp"><span class="Lb">library “libstats”</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/arb.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/qmath.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/stats.h</a>></code></p> -<section class="Ss"> -<h2 class="Ss" id="Stats_Blob_Template_Management_Functions"><a class="permalink" href="#Stats_Blob_Template_Management_Functions">Stats - Blob Template Management Functions</a></h2> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_tpl_alloc</code>(<var class="Fa">const char - *name</var>, <var class="Fa">uint32_t flags</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_tpl_fetch_allocid</code>(<var class="Fa">const char - *name</var>, <var class="Fa">uint32_t hash</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_tpl_fetch</code>(<var class="Fa">int tpl_id</var>, - <var class="Fa">struct statsblob_tpl **tpl</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_tpl_id2name</code>(<var class="Fa">uint32_t - tpl_id</var>, <var class="Fa">char *buf</var>, <var class="Fa">size_t - len</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_tpl_sample_rates</code>(<var class="Fa">SYSCTL_HANDLER_ARGS</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_tpl_sample_rollthedice</code>(<var class="Fa">struct - stats_tpl_sample_rate *rates</var>, <var class="Fa">int nrates</var>, - <var class="Fa">void *seed_bytes</var>, <var class="Fa">size_t - seed_len</var>);</p> -<p class="Pp"><var class="Ft">struct voistatspec</var> - <br/> - <code class="Fn">STATS_VSS_SUM</code>();</p> -<p class="Pp"><var class="Ft">struct voistatspec</var> - <br/> - <code class="Fn">STATS_VSS_MAX</code>();</p> -<p class="Pp"><var class="Ft">struct voistatspec</var> - <br/> - <code class="Fn">STATS_VSS_MIN</code>();</p> -<p class="Pp"><var class="Ft">struct voistatspec</var> - <br/> - <code class="Fn">STATS_VSS_CRHIST<32|64>_LIN</code>(<var class="Fa">lb</var>, - <var class="Fa">ub</var>, <var class="Fa">stepinc</var>, - <var class="Fa">vsdflags</var>);</p> -<p class="Pp"><var class="Ft">struct voistatspec</var> - <br/> - <code class="Fn">STATS_VSS_CRHIST<32|64>_EXP</code>(<var class="Fa">lb</var>, - <var class="Fa">ub</var>, <var class="Fa">stepbase</var>, - <var class="Fa">stepexp</var>, <var class="Fa">vsdflags</var>);</p> -<p class="Pp"><var class="Ft">struct voistatspec</var> - <br/> - <code class="Fn">STATS_VSS_CRHIST<32|64>_LINEXP</code>(<var class="Fa">lb</var>, - <var class="Fa">ub</var>, <var class="Fa">nlinsteps</var>, - <var class="Fa">stepbase</var>, <var class="Fa">vsdflags</var>);</p> -<p class="Pp"><var class="Ft">struct voistatspec</var> - <br/> - <code class="Fn">STATS_VSS_CRHIST<32|64>_USR</code>(<b class="Sy">HBKTS</b>(<a class="permalink" href="#CRBKT"><b class="Sy" id="CRBKT">CRBKT</b></a>(<i class="Em">lb</i>), - <i class="Em">...</i>), <var class="Fa">vsdflags</var>);</p> -<p class="Pp"><var class="Ft">struct voistatspec</var> - <br/> - <code class="Fn">STATS_VSS_DRHIST<32|64>_USR</code>(<b class="Sy">HBKTS</b>(<a class="permalink" href="#DRBKT"><b class="Sy" id="DRBKT">DRBKT</b></a>(<i class="Em">lb</i>, - <a class="permalink" href="#ub"><i class="Em" id="ub">ub</i></a>), - <i class="Em">...</i>), <var class="Fa">vsdflags</var>);</p> -<p class="Pp"><var class="Ft">struct voistatspec</var> - <br/> - <code class="Fn">STATS_VSS_DVHIST<32|64>_USR</code>(<b class="Sy">HBKTS</b>(<a class="permalink" href="#DVBKT"><b class="Sy" id="DVBKT">DVBKT</b></a>(<a class="permalink" href="#val"><i class="Em" id="val">val</i></a>), - <i class="Em">...</i>), <var class="Fa">vsdflags</var>);</p> -<p class="Pp"><var class="Ft">struct voistatspec</var> - <br/> - <code class="Fn">STATS_VSS_TDGSTCLUST<32|64></code>(<var class="Fa">nctroids</var>, - <var class="Fa">prec</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_tpl_add_voistats</code>(<var class="Fa">uint32_t - tpl_id</var>, <var class="Fa">int32_t voi_id</var>, <var class="Fa">const - char *voi_name</var>, <var class="Fa">enum vsd_dtype voi_dtype</var>, - <var class="Fa">uint32_t nvss</var>, <var class="Fa">struct voistatspec - *vss</var>, <var class="Fa">uint32_t flags</var>);</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Stats_Blob_Data_Gathering_Functions"><a class="permalink" href="#Stats_Blob_Data_Gathering_Functions">Stats - Blob Data Gathering Functions</a></h2> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_voi_update_<abs|rel>_<dtype></code>(<var class="Fa">struct - statsblob *sb</var>, <var class="Fa">int32_t voi_id</var>, - <var class="Fa"><dtype> voival</var>);</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Stats_Blob_Utility_Functions"><a class="permalink" href="#Stats_Blob_Utility_Functions">Stats - Blob Utility Functions</a></h2> -<p class="Pp"><var class="Ft">struct statsblob *</var> - <br/> - <code class="Fn">stats_blob_alloc</code>(<var class="Fa">uint32_t - tpl_id</var>, <var class="Fa">uint32_t flags</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_blob_init</code>(<var class="Fa">struct statsblob - *sb</var>, <var class="Fa">uint32_t tpl_id</var>, <var class="Fa">uint32_t - flags</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_blob_clone</code>(<var class="Fa">struct statsblob - **dst</var>, <var class="Fa">size_t dstmaxsz</var>, <var class="Fa">struct - statsblob *src</var>, <var class="Fa">uint32_t flags</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">stats_blob_destroy</code>(<var class="Fa">struct statsblob - *sb</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_voistat_fetch_dptr</code>(<var class="Fa">struct - statsblob *sb</var>, <var class="Fa">int32_t voi_id</var>, - <var class="Fa">enum voi_stype stype</var>, <var class="Fa">enum vsd_dtype - *retdtype</var>, <var class="Fa">struct voistatdata **retvsd</var>, - <var class="Fa">size_t *retvsdsz</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_voistat_fetch_<dtype></code>(<var class="Fa">struct - statsblob *sb</var>, <var class="Fa">int32_t voi_id</var>, - <var class="Fa">enum voi_stype stype</var>, <var class="Fa"><dtype> - *ret</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_blob_snapshot</code>(<var class="Fa">struct statsblob - **dst</var>, <var class="Fa">size_t dstmaxsz</var>, <var class="Fa">struct - statsblob *src</var>, <var class="Fa">uint32_t flags</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_blob_tostr</code>(<var class="Fa">struct statsblob - *sb</var>, <var class="Fa">struct sbuf *buf</var>, <var class="Fa">enum - sb_str_fmt fmt</var>, <var class="Fa">uint32_t flags</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_voistatdata_tostr</code>(<var class="Fa">const struct - voistatdata *vsd</var>, <var class="Fa">enum vsd_dtype dtype</var>, - <var class="Fa">enum sb_str_fmt fmt</var>, <var class="Fa">struct sbuf - *buf</var>, <var class="Fa">int objdump</var>);</p> -<p class="Pp"><var class="Ft">typedef int</var> - <br/> - <code class="Fn">(*stats_blob_visitcb_t)</code>(<var class="Fa" style="white-space: nowrap;">struct - sb_visit *sbv</var>, <var class="Fa" style="white-space: nowrap;">void - *usrctx</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">stats_blob_visit</code>(<var class="Fa">struct statsblob - *sb</var>, <var class="Fa">stats_blob_visitcb_t func</var>, - <var class="Fa">void *usrctx</var>);</p> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">stats</code> framework facilitates real-time - kernel and user space statistics gathering. The framework is built around - the “statsblob”, an object embedded within a contiguous memory - allocation that is mostly opaque to consumers and stores all required state. - A “statsblob” object can itself be embedded within other - objects either directly or indirectly using a pointer.</p> -<p class="Pp">Objects or subsystems for which statistics are to be gathered are - initialized from a template “statsblob”, which acts as the - blueprint for an arbitrary set of Variables Of Interest (VOIs) and their - associated statistics. Each template defines a schema plus associated - metadata, which are kept separate to minimize the memory footprint of - blobs.</p> -<p class="Pp">Data gathering hook functions added at appropriate locations - within the code base of interest feed VOI data into the framework for - processing.</p> -<p class="Pp">Each “statsblob”, consists of a - <var class="Vt">struct statsblob</var> header and opaque internal blob - structure per the following diagram:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>--------------------------------------------------------- -| struct | uint8_t | -| statsblob | opaque[] | ----------------------------------------------------------</pre> -</div> -<p class="Pp">The publicly visible 8-byte header is defined as:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>struct statsblob { - uint8_t abi; - uint8_t endian; - uint16_t flags; - uint16_t maxsz; - uint16_t cursz; - uint8_t opaque[]; -};</pre> -</div> -<p class="Pp"><var class="Va">abi</var> specifies which API version the blob's - <var class="Va">opaque</var> internals conform to - (<code class="Dv">STATS_ABI_V1 is the only version currently - defined</code>). <var class="Va">endian</var> specifies the endianness of - the blob's fields (<code class="Dv">SB_LE</code> for little endian, - <code class="Dv">SB_BE</code> for big endian, or - <code class="Dv">SB_UE</code> for unknown endianness). - <var class="Va">cursz</var> specifies the size of the blob, while - <var class="Va">maxsz</var> specifies the size of the underlying memory - allocation in which the blob is embedded. Both <var class="Va">cursz</var> - and <var class="Va">maxsz</var> default to units of bytes, unless a flag is - set in <var class="Va">flags</var> that dictates otherwise.</p> -<p class="Pp">Templates are constructed by associating arbitrary VOI IDs with a - set of statistics, where each statistic is specified using a - <var class="Vt">struct voistatspec</var> per the definition below:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>struct voistatspec { - vss_hlpr_fn hlpr; - struct vss_hlpr_info *hlprinfo; - struct voistatdata *iv; - size_t vsdsz; - uint32_t flags; - enum vsd_dtype vs_dtype : 8; - enum voi_stype stype : 8; -};</pre> -</div> -<p class="Pp" id="STATS_VSS_*">It is generally expected that consumers will not - work with <var class="Vt">struct voistatspec</var> directly, and instead use - the - <a class="permalink" href="#STATS_VSS_*"><code class="Fn">STATS_VSS_*</code></a>() - helper macros.</p> -<p class="Pp">The <code class="Nm">stats</code> framework offers the following - statistics for association with VOIs:</p> -<dl class="Bl-tag"> - <dt id="VS_STYPE_SUM"><a class="permalink" href="#VS_STYPE_SUM"><code class="Dv">VS_STYPE_SUM</code></a></dt> - <dd>The sum of VOI values.</dd> - <dt id="VS_STYPE_MAX"><a class="permalink" href="#VS_STYPE_MAX"><code class="Dv">VS_STYPE_MAX</code></a></dt> - <dd>The maximum VOI value.</dd> - <dt id="VS_STYPE_MIN"><a class="permalink" href="#VS_STYPE_MIN"><code class="Dv">VS_STYPE_MIN</code></a></dt> - <dd>The minimum VOI value.</dd> - <dt id="VS_STYPE_HIST"><a class="permalink" href="#VS_STYPE_HIST"><code class="Dv">VS_STYPE_HIST</code></a></dt> - <dd>A static bucket histogram of VOI values, including a count of - “out-of-band/bucket” values which did not match any bucket. - Histograms can be specified as - “<a class="permalink" href="#C"><i class="Em" id="C">C</i></a>ontinuous - <i class="Em">R</i>ange” (CRHIST), - “<i class="Em">D</i>iscrete <i class="Em">R</i>ange” - (DRHIST) or “<i class="Em">D</i>iscrete - <a class="permalink" href="#V"><i class="Em" id="V">V</i></a>alue” - (DVHIST), with 32 or 64 bit bucket counters, depending on the VOI - semantics.</dd> - <dt id="VS_STYPE_TDGST"><a class="permalink" href="#VS_STYPE_TDGST"><code class="Dv">VS_STYPE_TDGST</code></a></dt> - <dd>A dynamic bucket histogram of VOI values based on the t-digest method - (refer to the t-digest paper in the <a class="Sx" href="#SEE_ALSO">SEE - ALSO</a> section below).</dd> -</dl> -<p class="Pp">A “visitor software design pattern”-like scheme is - employed to facilitate iterating over a blob's data without concern for the - blob's structure. The data provided to visitor callback functions is - encapsulated in <var class="Vt">struct sb_visit</var> per the definition - below:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>struct sb_visit { - struct voistatdata *vs_data; - uint32_t tplhash; - uint32_t flags; - int16_t voi_id; - int16_t vs_dsz; - enum vsd_dtype voi_dtype : 8; - enum vsd_dtype vs_dtype : 8; - int8_t vs_stype; - uint16_t vs_errs; -};</pre> -</div> -<p class="Pp" id="stats_tpl_sample_rates">The - <a class="permalink" href="#stats_tpl_sample_rates"><code class="Fn">stats_tpl_sample_rates</code></a>() - and <code class="Fn">stats_tpl_sample_rollthedice</code>() functions utilize - <var class="Vt">struct stats_tpl_sample_rate</var> to encapsulate - per-template sample rate information per the definition below:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>struct stats_tpl_sample_rate { - int32_t tpl_slot_id; - uint32_t tpl_sample_pct; -};</pre> -</div> -<p class="Pp" id="stats_tpl_alloc">The <var class="Va">tpl_slot_id</var> member - holds the template's slot ID obtained from - <a class="permalink" href="#stats_tpl_alloc"><code class="Fn">stats_tpl_alloc</code></a>() - or <code class="Fn">stats_tpl_fetch_allocid</code>(). The - <var class="Va">tpl_sample_pct</var> member holds the template's sample rate - as an integer percentage in the range [0,100].</p> -<p class="Pp" id="stats_tpl_sample_rates~2">The - <var class="Vt">stats_tpl_sr_cb_t</var> conformant function pointer that is - required as the <var class="Fa">arg1</var> of - <a class="permalink" href="#stats_tpl_sample_rates~2"><code class="Fn">stats_tpl_sample_rates</code></a>() - is defined as:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>enum stats_tpl_sr_cb_action { - TPL_SR_UNLOCKED_GET, - TPL_SR_RLOCKED_GET, - TPL_SR_RUNLOCK, - TPL_SR_PUT -}; -typedef int (*stats_tpl_sr_cb_t)(enum stats_tpl_sr_cb_action action, - struct stats_tpl_sample_rate **rates, int *nrates, void *ctx);</pre> -</div> -<p class="Pp">It is required that a conformant function:</p> -<ul class="Bl-dash"> - <li>Return an appropriate <a class="Xr">errno(2)</a> on error, otherwise - 0.</li> - <li>When called with "action == TPL_SR_*_GET", return the - subsystem's rates list ptr and count, locked or unlocked as - requested.</li> - <li>When called with "action == TPL_SR_RUNLOCK", unlock the - subsystem's rates list ptr and count. Pair with a prior "action == - TPL_SR_RLOCKED_GET" call.</li> - <li id="stats_tpl_sample_rates~3">When called with "action == - TPL_SR_PUT", update the subsystem's rates list ptr and count to the - sysctl processed values and return the inactive list details in - <var class="Fa">rates</var> and <var class="Fa">nrates</var> for garbage - collection by - <a class="permalink" href="#stats_tpl_sample_rates~3"><code class="Fn">stats_tpl_sample_rates</code></a>().</li> -</ul> -<p class="Pp">Where templates need to be referenced via textual means, for - example via a MIB variable, the following string based template spec formats - can be used:</p> -<ol class="Bl-enum"> - <li>"<tplname>":<tplhash>, for example - "TCP_DEFAULT":1731235399</li> - <li>"<tplname>", for example "TCP_DEFAULT"</li> - <li>:<tplhash>, for example :1731235399</li> -</ol> -<p class="Pp">The first form is the normative spec format generated by the - framework, while the second and third forms are convenience formats - primarily for user input. The use of inverted commas around the template - name is optional.</p> -<section class="Ss"> -<h2 class="Ss" id="MIB_Variables"><a class="permalink" href="#MIB_Variables">MIB - Variables</a></h2> -<p class="Pp">The in-kernel <code class="Nm">stats</code> framework exposes the - following framework-specific variables in the - <var class="Va">kern.stats</var> branch of the <a class="Xr">sysctl(3)</a> - MIB.</p> -<dl class="Bl-tag"> - <dt>templates</dt> - <dd>Read-only CSV list of registered templates in normative template spec - form.</dd> -</dl> -</section> -<section class="Ss"> -<h2 class="Ss" id="Template_Management_Functions"><a class="permalink" href="#Template_Management_Functions">Template - Management Functions</a></h2> -<p class="Pp">The - <a class="permalink" href="#stats_tpl_alloc~2"><code class="Fn" id="stats_tpl_alloc~2">stats_tpl_alloc</code></a>() - function allocates a new template with the specified unique name and returns - its runtime-stable template slot ID for use with other API functions. The - <var class="Fa">flags</var> argument is currently unused.</p> -<p class="Pp" id="stats_tpl_fetch_allocid">The - <a class="permalink" href="#stats_tpl_fetch_allocid"><code class="Fn">stats_tpl_fetch_allocid</code></a>() - function returns the runtime-stable template slot ID of any registered - template matching the specified name and hash.</p> -<p class="Pp" id="stats_tpl_fetch">The - <a class="permalink" href="#stats_tpl_fetch"><code class="Fn">stats_tpl_fetch</code></a>() - function returns the pointer to the registered template object at the - specified template slot ID.</p> -<p class="Pp" id="stats_tpl_id2name">The - <a class="permalink" href="#stats_tpl_id2name"><code class="Fn">stats_tpl_id2name</code></a>() - function returns the name of the registered template object at the specified - template slot ID.</p> -<p class="Pp" id="stats_tpl_sample_rates~4">The - <a class="permalink" href="#stats_tpl_sample_rates~4"><code class="Fn">stats_tpl_sample_rates</code></a>() - function provides a generic handler for template sample rates management and - reporting via <a class="Xr">sysctl(3)</a> MIB variables. Subsystems can use - this function to create a subsystem-specific - <a class="Xr">SYSCTL_PROC(9)</a> MIB variable that manages and reports - subsystem-specific template sampling rates. Subsystems must supply a - <var class="Vt">stats_tpl_sr_cb_t</var> conformant function pointer as the - sysctl's <var class="Fa">arg1</var>, which is a callback used to interact - with the subsystem's stats template sample rates list. Subsystems can - optionally specify the sysctl's <var class="Fa">arg2</var> as non-zero, - which causes a zero-initialized allocation of arg2-sized contextual memory - to be heap-allocated and passed in to all subsystem callbacks made during - the operation of <code class="Fn">stats_tpl_sample_rates</code>().</p> -<p class="Pp" id="stats_tpl_sample_rollthedice">The - <a class="permalink" href="#stats_tpl_sample_rollthedice"><code class="Fn">stats_tpl_sample_rollthedice</code></a>() - function makes a weighted random template selection from the supplied array - of template sampling rates. The cumulative percentage of all sampling rates - should not exceed 100. If no seed is supplied, a PRNG is used to generate a - true random number so that every selection is independent. If a seed is - supplied, selection will be made randomly across different seeds, but - deterministically given the same seed.</p> -<p class="Pp" id="stats_tpl_add_voistats">The - <a class="permalink" href="#stats_tpl_add_voistats"><code class="Fn">stats_tpl_add_voistats</code></a>() - function is used to add a VOI and associated set of statistics to the - registered template object at the specified template slot ID. The set of - statistics is passed as an array of <var class="Vt">struct voistatspec</var> - which can be initialized using the <code class="Fn">STATS_VSS_*</code>() - helper macros or manually for non-standard use cases. For static - <var class="Fa">vss</var> arrays, the <var class="Fa">nvss</var> count of - array elements can be determined by passing <var class="Fa">vss</var> to the - <a class="permalink" href="#NVSS"><code class="Fn" id="NVSS">NVSS</code></a>() - macro. The <code class="Dv">SB_VOI_RELUPDATE</code> flag can be passed to - configure the VOI for use with - <a class="permalink" href="#stats_voi_update_rel__dtype_"><code class="Fn" id="stats_voi_update_rel__dtype_">stats_voi_update_rel_<dtype></code></a>(), - which entails maintaining an extra 8 bytes of state in the blob at each - update.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Data_Gathering_Functions"><a class="permalink" href="#Data_Gathering_Functions">Data - Gathering Functions</a></h2> -<p class="Pp">The - <a class="permalink" href="#stats_voi_update_abs__dtype_"><code class="Fn" id="stats_voi_update_abs__dtype_">stats_voi_update_abs_<dtype></code></a>() - and <code class="Fn">stats_voi_update_rel_<dtype></code>() functions - both update all the statistics associated with the VOI identified by - <var class="Fa">voi_id</var>. The “abs” call uses - <var class="Fa">voival</var> as an absolute value, whereas the - “rel” call uses <var class="Fa">voival</var> as a value - relative to that of the previous update function call, by adding it to the - previous value and using the result for the update. Relative updates are - only possible for VOIs that were added to the template with the - <code class="Dv">SB_VOI_RELUPDATE</code> flag specified to - <code class="Fn">stats_tpl_add_voistats</code>().</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Utility_Functions"><a class="permalink" href="#Utility_Functions">Utility - Functions</a></h2> -<p class="Pp">The <code class="Fn">stats_blob_alloc</code>() function allocates - and initializes a new blob based on the registered template object at the - specified template slot ID.</p> -<p class="Pp" id="stats_blob_init">The - <a class="permalink" href="#stats_blob_init"><code class="Fn">stats_blob_init</code></a>() - function initializes a new blob in an existing memory allocation based on - the registered template object at the specified template slot ID.</p> -<p class="Pp" id="stats_blob_clone">The - <a class="permalink" href="#stats_blob_clone"><code class="Fn">stats_blob_clone</code></a>() - function duplicates the <var class="Fa">src</var> blob into - <var class="Fa">dst</var>, leaving only the <var class="Va">maxsz</var> - field of <var class="Fa">dst</var> untouched. The - <code class="Dv">SB_CLONE_ALLOCDST</code> flag can be passed to instruct the - function to allocate a new blob of appropriate size into which to clone - <var class="Fa">src</var>, storing the new pointer in - <var class="Fa">*dst</var>. The - <code class="Dv">SB_CLONE_USRDSTNOFAULT</code> or - <code class="Dv">SB_CLONE_USRDST</code> flags can be set to respectively - signal that <a class="Xr">copyout_nofault(9)</a> or - <a class="Xr">copyout(9)</a> should be used because - <var class="Fa">*dst</var> is a user space address.</p> -<p class="Pp" id="stats_blob_snapshot">The - <a class="permalink" href="#stats_blob_snapshot"><code class="Fn">stats_blob_snapshot</code></a>() - function calls <code class="Fn">stats_blob_clone</code>() to obtain a copy - of <var class="Fa">src</var> and then performs any additional functions - required to produce a coherent blob snapshot. The flags interpreted by - <code class="Fn">stats_blob_clone</code>() also apply to - <code class="Fn">stats_blob_snapshot</code>(). Additionally, the - <code class="Dv">SB_CLONE_RSTSRC</code> flag can be used to effect a reset - of the <var class="Fa">src</var> blob's statistics after a snapshot is - successfully taken.</p> -<p class="Pp" id="stats_blob_destroy">The - <a class="permalink" href="#stats_blob_destroy"><code class="Fn">stats_blob_destroy</code></a>() - function destroys a blob previously created with - <a class="permalink" href="#stats_blob_alloc"><code class="Fn" id="stats_blob_alloc">stats_blob_alloc</code></a>(), - <code class="Fn">stats_blob_clone</code>() or - <code class="Fn">stats_blob_snapshot</code>().</p> -<p class="Pp" id="stats_blob_visit">The - <a class="permalink" href="#stats_blob_visit"><code class="Fn">stats_blob_visit</code></a>() - function allows the caller to iterate over the contents of a blob. The - callback function <var class="Fa">func</var> is called for every VOI and - statistic in the blob, passing a <var class="Vt">struct sb_visit</var> and - the user context argument <var class="Fa">usrctx</var> to the callback - function. The <var class="Fa">sbv</var> passed to the callback function may - have one or more of the following flags set in the - <var class="Va">flags</var> struct member to provide useful metadata about - the iteration: <code class="Dv">SB_IT_FIRST_CB</code>, - <code class="Dv">SB_IT_LAST_CB</code>, - <code class="Dv">SB_IT_FIRST_VOI</code>, - <code class="Dv">SB_IT_LAST_VOI</code>, - <code class="Dv">SB_IT_FIRST_VOISTAT</code>, - <code class="Dv">SB_IT_LAST_VOISTAT</code>, - <code class="Dv">SB_IT_NULLVOI</code> and - <code class="Dv">SB_IT_NULLVOISTAT</code>. Returning a non-zero value from - the callback function terminates the iteration.</p> -<p class="Pp" id="stats_blob_tostr">The - <a class="permalink" href="#stats_blob_tostr"><code class="Fn">stats_blob_tostr</code></a>() - renders a string representation of a blob into the <a class="Xr">sbuf(9)</a> - <var class="Fa">buf</var>. Currently supported render formats are - <code class="Dv">SB_STRFMT_FREEFORM</code> and - <code class="Dv">SB_STRFMT_JSON</code>. The - <code class="Dv">SB_TOSTR_OBJDUMP</code> flag can be passed to render - version specific opaque implementation detail for debugging or - string-to-binary blob reconstruction purposes. The - <code class="Dv">SB_TOSTR_META</code> flag can be passed to render template - metadata into the string representation, using the blob's template hash to - lookup the corresponding template.</p> -<p class="Pp" id="stats_voistatdata_tostr">The - <a class="permalink" href="#stats_voistatdata_tostr"><code class="Fn">stats_voistatdata_tostr</code></a>() - renders a string representation of an individual statistic's data into the - <a class="Xr">sbuf(9)</a> <var class="Fa">buf</var>. The same render formats - supported by the <code class="Fn">stats_blob_tostr</code>() function can be - specified, and the <var class="Fa">objdump</var> boolean has the same - meaning as the <code class="Dv">SB_TOSTR_OBJDUMP</code> flag.</p> -<p class="Pp" id="stats_voistat_fetch_dptr">The - <a class="permalink" href="#stats_voistat_fetch_dptr"><code class="Fn">stats_voistat_fetch_dptr</code></a>() - function returns an internal blob pointer to the specified - <var class="Fa">stype</var> statistic data for the VOI - <var class="Fa">voi_id</var>. The - <a class="permalink" href="#stats_voistat_fetch__dtype_"><code class="Fn" id="stats_voistat_fetch__dtype_">stats_voistat_fetch_<dtype></code></a>() - functions are convenience wrappers around - <code class="Fn">stats_voistat_fetch_dptr</code>() to perform the extraction - for simple data types.</p> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="IMPLEMENTATION_NOTES"><a class="permalink" href="#IMPLEMENTATION_NOTES">IMPLEMENTATION - NOTES</a></h1> -<p class="Pp">The following notes apply to STATS_ABI_V1 format statsblobs.</p> -<section class="Ss"> -<h2 class="Ss" id="Space-Time_Complexity"><a class="permalink" href="#Space-Time_Complexity">Space-Time - Complexity</a></h2> -<p class="Pp">Blobs are laid out as three distinct memory regions following the - header:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>------------------------------------------------------ -| struct | struct | struct | struct | -| statsblobv1 | voi [] | voistat [] | voistatdata [] | -------------------------------------------------------</pre> -</div> -<p class="Pp">Blobs store VOI and statistic blob state (8 bytes for - <var class="Vt">struct voi</var> and 8 bytes for <var class="Vt">struct - voistat</var> respectively) in sparse arrays, using the - <var class="Fa">voi_id</var> and <var class="Vt">enum voi_stype</var> as - array indices. This allows O(1) access to any voi/voistat pair in the blob, - at the expense of 8 bytes of wasted memory per vacant slot for templates - which do not specify contiguously numbered VOIs and/or statistic types. Data - storage for statistics is only allocated for non-vacant slot pairs.</p> -<p class="Pp">To provide a concrete example, a blob with the following - specification:</p> -<ul class="Bl-dash"> - <li>Two VOIs; ID 0 and 2; added to the template in that order</li> - <li>VOI 0 is of data type <var class="Vt">int64_t</var>, is configured with - <code class="Dv">SB_VOI_RELUPDATE</code> to enable support for relative - updates using - <code class="Fn">stats_voi_update_rel_<dtype></code>(), and has a - <code class="Dv">VS_STYPE_MIN</code> statistic associated with it.</li> - <li>VOI 2 is of data type <var class="Vt">uint32_t</var> with - <code class="Dv">VS_STYPE_SUM</code> and - <code class="Dv">VS_STYPE_MAX</code> statistics associated with it.</li> -</ul> -<p class="Pp">would have the following memory layout:</p> -<div class="Bd Pp Li"> -<pre>-------------------------------------- -| header | struct statsblobv1, 32 bytes -|------------------------------------| -| voi[0] | struct voi, 8 bytes -| voi[1] (vacant) | struct voi, 8 bytes -| voi[2] | struct voi, 8 bytes -|------------------------------------| -| voi[2]voistat[VOISTATE] (vacant) | struct voistat, 8 bytes -| voi[2]voistat[SUM] | struct voistat, 8 bytes -| voi[2]voistat[MAX] | struct voistat, 8 bytes -| voi[0]voistat[VOISTATE] | struct voistat, 8 bytes -| voi[0]voistat[SUM] (vacant) | struct voistat, 8 bytes -| voi[0]voistat[MAX] (vacant) | struct voistat, 8 bytes -| voi[0]voistat[MIN] | struct voistat, 8 bytes -|------------------------------------| -| voi[2]voistat[SUM]voistatdata | struct voistatdata_int32, 4 bytes -| voi[2]voistat[MAX]voistatdata | struct voistatdata_int32, 4 bytes -| voi[0]voistat[VOISTATE]voistatdata | struct voistatdata_numeric, 8 bytes -| voi[0]voistat[MIN]voistatdata | struct voistatdata_int64, 8 bytes --------------------------------------- - TOTAL 136 bytes</pre> -</div> -<p class="Pp">When rendered to string format using - <code class="Fn">stats_blob_tostr</code>(), the - <code class="Dv">SB_STRFMT_FREEFORM</code> <var class="Fa">fmt</var> and the - <code class="Dv">SB_TOSTR_OBJDUMP</code> flag, the rendered output is:</p> -<div class="Bd Pp Li"> -<pre>struct statsblobv1@0x8016250a0, abi=1, endian=1, maxsz=136, cursz=136, \ - created=6294158585626144, lastrst=6294158585626144, flags=0x0000, \ - stats_off=56, statsdata_off=112, tplhash=2994056564 - vois[0]: id=0, name="", flags=0x0001, dtype=INT_S64, voistatmaxid=3, \ - stats_off=80 - vois[0]stat[0]: stype=VOISTATE, flags=0x0000, dtype=VOISTATE, \ - dsz=8, data_off=120 - voistatdata: prev=0 - vois[0]stat[1]: stype=-1 - vois[0]stat[2]: stype=-1 - vois[0]stat[3]: stype=MIN, flags=0x0000, dtype=INT_S64, \ - dsz=8, data_off=128 - voistatdata: 9223372036854775807 - vois[1]: id=-1 - vois[2]: id=2, name="", flags=0x0000, dtype=INT_U32, voistatmaxid=2, \ - stats_off=56 - vois[2]stat[0]: stype=-1 - vois[2]stat[1]: stype=SUM, flags=0x0000, dtype=INT_U32, dsz=4, \ - data_off=112 - voistatdata: 0 - vois[2]stat[2]: stype=MAX, flags=0x0000, dtype=INT_U32, dsz=4, \ - data_off=116 - voistatdata: 0</pre> -</div> -<p class="Pp">Note: The "\" present in the rendered output above - indicates a manual line break inserted to keep the man page within 80 - columns and is not part of the actual output.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Locking"><a class="permalink" href="#Locking">Locking</a></h2> -<p class="Pp">The <code class="Nm">stats</code> framework does not provide any - concurrency protection at the individual blob level, instead requiring that - consumers guarantee mutual exclusion when calling API functions that - reference a non-template blob.</p> -<p class="Pp">The list of templates is protected with a - <a class="Xr">rwlock(9)</a> in-kernel, and <a class="Xr">pthread(3)</a> rw - lock in user space to support concurrency between template management and - blob initialization operations.</p> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN - VALUES</a></h1> -<p class="Pp"><code class="Fn">stats_tpl_alloc</code>() returns a runtime-stable - template slot ID on success, or a negative errno on failure. -EINVAL is - returned if any problems are detected with the arguments. -EEXIST is - returned if an existing template is registered with the same name. -ENOMEM - is returned if a required memory allocation fails.</p> -<p class="Pp"><code class="Fn">stats_tpl_fetch_allocid</code>() returns a - runtime-stable template slot ID, or negative errno on failure. -ESRCH is - returned if no registered template matches the specified name and/or - hash.</p> -<p class="Pp"><code class="Fn">stats_tpl_fetch</code>() returns 0 on success, or - ENOENT if an invalid <var class="Fa">tpl_id</var> is specified.</p> -<p class="Pp"><code class="Fn">stats_tpl_id2name</code>() returns 0 on success, - or an errno on failure. EOVERFLOW is returned if the length of - <var class="Fa">buf</var> specified by <var class="Fa">len</var> is too - short to hold the template's name. ENOENT is returned if an invalid - <var class="Fa">tpl_id</var> is specified.</p> -<p class="Pp"><code class="Fn">stats_tpl_sample_rollthedice</code>() returns a - valid template slot id selected from <var class="Fa">rates</var> or -1 if a - NULL selection was made, that is no stats collection this roll.</p> -<p class="Pp"><code class="Fn">stats_tpl_add_voistats</code>() return 0 on - success, or an errno on failure. EINVAL is returned if any problems are - detected with the arguments. EFBIG is returned if the resulting blob would - have exceeded the maximum size. EOPNOTSUPP is returned if an attempt is made - to add more VOI stats to a previously configured VOI. ENOMEM is returned if - a required memory allocation fails.</p> -<p class="Pp"><code class="Fn">stats_voi_update_abs_<dtype></code>() and - <code class="Fn">stats_voi_update_rel_<dtype></code>() return 0 on - success, or EINVAL if any problems are detected with the arguments.</p> -<p class="Pp"><code class="Fn">stats_blob_init</code>() returns 0 on success, or - an errno on failure. EINVAL is returned if any problems are detected with - the arguments. EOVERFLOW is returned if the template blob's - <var class="Fa">cursz</var> is larger than the <var class="Fa">maxsz</var> - of the blob being initialized.</p> -<p class="Pp"><code class="Fn">stats_blob_alloc</code>() returns a pointer to a - newly allocated and initialized blob based on the specified template with - slot ID <var class="Fa">tpl_id</var>, or NULL if the memory allocation - failed.</p> -<p class="Pp"><code class="Fn">stats_blob_clone</code>() and - <code class="Fn">stats_blob_snapshot</code>() return 0 on success, or an - errno on failure. EINVAL is returned if any problems are detected with the - arguments. ENOMEM is returned if the SB_CLONE_ALLOCDST flag was specified - and the memory allocation for <var class="Fa">dst</var> fails. EOVERFLOW is - returned if the src blob's <var class="Fa">cursz</var> is larger than the - <var class="Fa">maxsz</var> of the <var class="Fa">dst</var> blob.</p> -<p class="Pp"><code class="Fn">stats_blob_visit</code>() returns 0 on success, - or EINVAL if any problems are detected with the arguments.</p> -<p class="Pp"><code class="Fn">stats_blob_tostr</code>() and - <code class="Fn">stats_voistatdata_tostr</code>() return 0 on success, or an - errno on failure. EINVAL is returned if any problems are detected with the - arguments, otherwise any error returned by - <code class="Fn">sbuf_error</code>() for <var class="Fa">buf</var> is - returned.</p> -<p class="Pp"><code class="Fn">stats_voistat_fetch_dptr</code>() returns 0 on - success, or EINVAL if any problems are detected with the arguments.</p> -<p class="Pp"><code class="Fn">stats_voistat_fetch_<dtype></code>() - returns 0 on success, or an errno on failure. EINVAL is returned if any - problems are detected with the arguments. EFTYPE is returned if the - requested data type does not match the blob's data type for the specified - <var class="Fa">voi_id</var> and <var class="Fa">stype</var>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">errno(2)</a>, <a class="Xr">arb(3)</a>, - <a class="Xr">qmath(3)</a>, <a class="Xr">tcp(4)</a>, - <a class="Xr">sbuf(9)</a></p> -<p class="Pp"><cite class="Rs"><span class="RsA">Ted Dunning</span> and - <span class="RsA">Otmar Ertl</span>, <span class="RsT">Computing Extremely - Accurate Quantiles Using t-digests</span>, - <a class="RsU" href="https://github.com/tdunning/t-digest/raw/master/docs/t-digest-paper/histo.pdf">https://github.com/tdunning/t-digest/raw/master/docs/t-digest-paper/histo.pdf</a>.</cite></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The <code class="Nm">stats</code> framework first appeared in - <span class="Ux">FreeBSD 13.0</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">The <code class="Nm">stats</code> framework and this manual page - were written by <span class="An">Lawrence Stewart</span> - ⟨lstewart@FreeBSD.org⟩ and sponsored by Netflix, Inc.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1> -<p class="Pp">Granularity of timing-dependent network statistics, in particular - TCP_RTT, depends on the <code class="Dv">HZ</code> timer. To minimize the - measurement error avoid using HZ lower than 1000.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">December 2, 2019</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |