diff options
Diffstat (limited to 'static/freebsd/man3/stats.3 3.html')
| -rw-r--r-- | static/freebsd/man3/stats.3 3.html | 725 |
1 files changed, 725 insertions, 0 deletions
diff --git a/static/freebsd/man3/stats.3 3.html b/static/freebsd/man3/stats.3 3.html new file mode 100644 index 00000000..fb277eab --- /dev/null +++ b/static/freebsd/man3/stats.3 3.html @@ -0,0 +1,725 @@ +<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> |