11a13f2e6SEdward Tomasz Napierala.\" 21a13f2e6SEdward Tomasz Napierala.\" Copyright (c) 2016-2018 Netflix, Inc. 31a13f2e6SEdward Tomasz Napierala.\" All rights reserved. 41a13f2e6SEdward Tomasz Napierala.\" 51a13f2e6SEdward Tomasz Napierala.\" Redistribution and use in source and binary forms, with or without 61a13f2e6SEdward Tomasz Napierala.\" modification, are permitted provided that the following conditions 71a13f2e6SEdward Tomasz Napierala.\" are met: 81a13f2e6SEdward Tomasz Napierala.\" 1. Redistributions of source code must retain the above copyright 91a13f2e6SEdward Tomasz Napierala.\" notice, this list of conditions, and the following disclaimer, 101a13f2e6SEdward Tomasz Napierala.\" without modification, immediately at the beginning of the file. 111a13f2e6SEdward Tomasz Napierala.\" 2. The name of the author may not be used to endorse or promote products 121a13f2e6SEdward Tomasz Napierala.\" derived from this software without specific prior written permission. 131a13f2e6SEdward Tomasz Napierala.\" 141a13f2e6SEdward Tomasz Napierala.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 151a13f2e6SEdward Tomasz Napierala.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 161a13f2e6SEdward Tomasz Napierala.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 171a13f2e6SEdward Tomasz Napierala.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR 181a13f2e6SEdward Tomasz Napierala.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 191a13f2e6SEdward Tomasz Napierala.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 201a13f2e6SEdward Tomasz Napierala.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 211a13f2e6SEdward Tomasz Napierala.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 221a13f2e6SEdward Tomasz Napierala.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 231a13f2e6SEdward Tomasz Napierala.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 241a13f2e6SEdward Tomasz Napierala.\" SUCH DAMAGE. 251a13f2e6SEdward Tomasz Napierala.\" 26359d7273SEdward Tomasz Napierala.Dd December 2, 2019 271a13f2e6SEdward Tomasz Napierala.Dt STATS 3 281a13f2e6SEdward Tomasz Napierala.Os 291a13f2e6SEdward Tomasz Napierala.Sh NAME 301a13f2e6SEdward Tomasz Napierala.Nm stats 311a13f2e6SEdward Tomasz Napierala.Nd statistics gathering 321a13f2e6SEdward Tomasz Napierala.Sh LIBRARY 331a13f2e6SEdward Tomasz Napierala.Lb libstats 341a13f2e6SEdward Tomasz Napierala.Sh SYNOPSIS 351a13f2e6SEdward Tomasz Napierala.In sys/arb.h 361a13f2e6SEdward Tomasz Napierala.In sys/qmath.h 371a13f2e6SEdward Tomasz Napierala.In sys/stats.h 381a13f2e6SEdward Tomasz Napierala.Ss Stats Blob Template Management Functions 391a13f2e6SEdward Tomasz Napierala.Ft int 401a13f2e6SEdward Tomasz Napierala.Fo stats_tpl_alloc 411a13f2e6SEdward Tomasz Napierala.Fa "const char *name" 421a13f2e6SEdward Tomasz Napierala.Fa "uint32_t flags" 431a13f2e6SEdward Tomasz Napierala.Fc 441a13f2e6SEdward Tomasz Napierala.Ft int 451a13f2e6SEdward Tomasz Napierala.Fo stats_tpl_fetch_allocid 461a13f2e6SEdward Tomasz Napierala.Fa "const char *name" 471a13f2e6SEdward Tomasz Napierala.Fa "uint32_t hash" 481a13f2e6SEdward Tomasz Napierala.Fc 491a13f2e6SEdward Tomasz Napierala.Ft int 501a13f2e6SEdward Tomasz Napierala.Fo stats_tpl_fetch 511a13f2e6SEdward Tomasz Napierala.Fa "int tpl_id" 521a13f2e6SEdward Tomasz Napierala.Fa "struct statsblob_tpl **tpl" 531a13f2e6SEdward Tomasz Napierala.Fc 541a13f2e6SEdward Tomasz Napierala.Ft int 551a13f2e6SEdward Tomasz Napierala.Fo stats_tpl_id2name 561a13f2e6SEdward Tomasz Napierala.Fa "uint32_t tpl_id" 571a13f2e6SEdward Tomasz Napierala.Fa "char *buf" 581a13f2e6SEdward Tomasz Napierala.Fa "size_t len" 591a13f2e6SEdward Tomasz Napierala.Fc 601a13f2e6SEdward Tomasz Napierala.Ft int 611a13f2e6SEdward Tomasz Napierala.Fo stats_tpl_sample_rates 621a13f2e6SEdward Tomasz Napierala.Fa "SYSCTL_HANDLER_ARGS" 631a13f2e6SEdward Tomasz Napierala.Fc 641a13f2e6SEdward Tomasz Napierala.Ft int 651a13f2e6SEdward Tomasz Napierala.Fo stats_tpl_sample_rollthedice 661a13f2e6SEdward Tomasz Napierala.Fa "struct stats_tpl_sample_rate *rates" 671a13f2e6SEdward Tomasz Napierala.Fa "int nrates" 681a13f2e6SEdward Tomasz Napierala.Fa "void *seed_bytes" 691a13f2e6SEdward Tomasz Napierala.Fa "size_t seed_len" 701a13f2e6SEdward Tomasz Napierala.Fc 711a13f2e6SEdward Tomasz Napierala.Ft struct voistatspec 721a13f2e6SEdward Tomasz Napierala.Fo STATS_VSS_SUM 731a13f2e6SEdward Tomasz Napierala.Fc 741a13f2e6SEdward Tomasz Napierala.Ft struct voistatspec 751a13f2e6SEdward Tomasz Napierala.Fo STATS_VSS_MAX 761a13f2e6SEdward Tomasz Napierala.Fc 771a13f2e6SEdward Tomasz Napierala.Ft struct voistatspec 781a13f2e6SEdward Tomasz Napierala.Fo STATS_VSS_MIN 791a13f2e6SEdward Tomasz Napierala.Fc 801a13f2e6SEdward Tomasz Napierala.Ft struct voistatspec 811a13f2e6SEdward Tomasz Napierala.Fo STATS_VSS_CRHIST<32|64>_LIN 821a13f2e6SEdward Tomasz Napierala.Fa "lb" 831a13f2e6SEdward Tomasz Napierala.Fa "ub" 841a13f2e6SEdward Tomasz Napierala.Fa "stepinc" 851a13f2e6SEdward Tomasz Napierala.Fa "vsdflags" 861a13f2e6SEdward Tomasz Napierala.Fc 871a13f2e6SEdward Tomasz Napierala.Ft struct voistatspec 881a13f2e6SEdward Tomasz Napierala.Fo STATS_VSS_CRHIST<32|64>_EXP 891a13f2e6SEdward Tomasz Napierala.Fa "lb" 901a13f2e6SEdward Tomasz Napierala.Fa "ub" 911a13f2e6SEdward Tomasz Napierala.Fa "stepbase" 921a13f2e6SEdward Tomasz Napierala.Fa "stepexp" 931a13f2e6SEdward Tomasz Napierala.Fa "vsdflags" 941a13f2e6SEdward Tomasz Napierala.Fc 951a13f2e6SEdward Tomasz Napierala.Ft struct voistatspec 961a13f2e6SEdward Tomasz Napierala.Fo "STATS_VSS_CRHIST<32|64>_LINEXP" 971a13f2e6SEdward Tomasz Napierala.Fa "lb" 981a13f2e6SEdward Tomasz Napierala.Fa "ub" 991a13f2e6SEdward Tomasz Napierala.Fa "nlinsteps" 1001a13f2e6SEdward Tomasz Napierala.Fa "stepbase" 1011a13f2e6SEdward Tomasz Napierala.Fa "vsdflags" 1021a13f2e6SEdward Tomasz Napierala.Fc 1031a13f2e6SEdward Tomasz Napierala.Ft struct voistatspec 1041a13f2e6SEdward Tomasz Napierala.Fo "STATS_VSS_CRHIST<32|64>_USR" 105*2d69f02cSGraham Percival.Fa Sy "HBKTS" Ns Pq Sy "CRBKT" Ns ( Em "lb" ) , "..." , 1061a13f2e6SEdward Tomasz Napierala.Fa "vsdflags" 1071a13f2e6SEdward Tomasz Napierala.Fc 1081a13f2e6SEdward Tomasz Napierala.Ft struct voistatspec 1091a13f2e6SEdward Tomasz Napierala.Fo "STATS_VSS_DRHIST<32|64>_USR" 110*2d69f02cSGraham Percival.Fa Sy "HBKTS" Ns Pq Sy "DRBKT" Ns ( Em "lb" , "ub" ) , "..." , 1111a13f2e6SEdward Tomasz Napierala.Fa "vsdflags" 1121a13f2e6SEdward Tomasz Napierala.Fc 1131a13f2e6SEdward Tomasz Napierala.Ft struct voistatspec 1141a13f2e6SEdward Tomasz Napierala.Fo "STATS_VSS_DVHIST<32|64>_USR" 115*2d69f02cSGraham Percival.Fa Sy "HBKTS" Ns Pq Sy "DVBKT" Ns ( Em "val" ) , "..." , 1161a13f2e6SEdward Tomasz Napierala.Fa "vsdflags" 1171a13f2e6SEdward Tomasz Napierala.Fc 1181a13f2e6SEdward Tomasz Napierala.Ft struct voistatspec 1191a13f2e6SEdward Tomasz Napierala.Fo STATS_VSS_TDGSTCLUST<32|64> 1201a13f2e6SEdward Tomasz Napierala.Fa "nctroids" 1211a13f2e6SEdward Tomasz Napierala.Fa "prec" 1221a13f2e6SEdward Tomasz Napierala.Fc 1231a13f2e6SEdward Tomasz Napierala.Ft int 1241a13f2e6SEdward Tomasz Napierala.Fo stats_tpl_add_voistats 1251a13f2e6SEdward Tomasz Napierala.Fa "uint32_t tpl_id" 1261a13f2e6SEdward Tomasz Napierala.Fa "int32_t voi_id" 1271a13f2e6SEdward Tomasz Napierala.Fa "const char *voi_name" 1281a13f2e6SEdward Tomasz Napierala.Fa "enum vsd_dtype voi_dtype" 1291a13f2e6SEdward Tomasz Napierala.Fa "uint32_t nvss" 1301a13f2e6SEdward Tomasz Napierala.Fa "struct voistatspec *vss" 1311a13f2e6SEdward Tomasz Napierala.Fa "uint32_t flags" 1321a13f2e6SEdward Tomasz Napierala.Fc 1331a13f2e6SEdward Tomasz Napierala.Ss Stats Blob Data Gathering Functions 1341a13f2e6SEdward Tomasz Napierala.Ft int 1351a13f2e6SEdward Tomasz Napierala.Fo stats_voi_update_<abs|rel>_<dtype> 1361a13f2e6SEdward Tomasz Napierala.Fa "struct statsblob *sb" 1371a13f2e6SEdward Tomasz Napierala.Fa "int32_t voi_id" 1381a13f2e6SEdward Tomasz Napierala.Fa "<dtype> voival" 1391a13f2e6SEdward Tomasz Napierala.Fc 1401a13f2e6SEdward Tomasz Napierala.Ss Stats Blob Utility Functions 1411a13f2e6SEdward Tomasz Napierala.Ft struct statsblob * 1421a13f2e6SEdward Tomasz Napierala.Fo stats_blob_alloc 1431a13f2e6SEdward Tomasz Napierala.Fa "uint32_t tpl_id" 1441a13f2e6SEdward Tomasz Napierala.Fa "uint32_t flags" 1451a13f2e6SEdward Tomasz Napierala.Fc 1461a13f2e6SEdward Tomasz Napierala.Ft int 1471a13f2e6SEdward Tomasz Napierala.Fo stats_blob_init 1481a13f2e6SEdward Tomasz Napierala.Fa "struct statsblob *sb" 1491a13f2e6SEdward Tomasz Napierala.Fa "uint32_t tpl_id" 1501a13f2e6SEdward Tomasz Napierala.Fa "uint32_t flags" 1511a13f2e6SEdward Tomasz Napierala.Fc 1521a13f2e6SEdward Tomasz Napierala.Ft int 1531a13f2e6SEdward Tomasz Napierala.Fo stats_blob_clone 1541a13f2e6SEdward Tomasz Napierala.Fa "struct statsblob **dst" 1551a13f2e6SEdward Tomasz Napierala.Fa "size_t dstmaxsz" 1561a13f2e6SEdward Tomasz Napierala.Fa "struct statsblob *src" 1571a13f2e6SEdward Tomasz Napierala.Fa "uint32_t flags" 1581a13f2e6SEdward Tomasz Napierala.Fc 1591a13f2e6SEdward Tomasz Napierala.Ft void 1601a13f2e6SEdward Tomasz Napierala.Fo stats_blob_destroy 1611a13f2e6SEdward Tomasz Napierala.Fa "struct statsblob *sb" 1621a13f2e6SEdward Tomasz Napierala.Fc 1631a13f2e6SEdward Tomasz Napierala.Ft int 1641a13f2e6SEdward Tomasz Napierala.Fo stats_voistat_fetch_dptr 1651a13f2e6SEdward Tomasz Napierala.Fa "struct statsblob *sb" 1661a13f2e6SEdward Tomasz Napierala.Fa "int32_t voi_id" 1671a13f2e6SEdward Tomasz Napierala.Fa "enum voi_stype stype" 1681a13f2e6SEdward Tomasz Napierala.Fa "enum vsd_dtype *retdtype" 1691a13f2e6SEdward Tomasz Napierala.Fa "struct voistatdata **retvsd" 1701a13f2e6SEdward Tomasz Napierala.Fa "size_t *retvsdsz" 1711a13f2e6SEdward Tomasz Napierala.Fc 1721a13f2e6SEdward Tomasz Napierala.Ft int 1731a13f2e6SEdward Tomasz Napierala.Fo stats_voistat_fetch_<dtype> 1741a13f2e6SEdward Tomasz Napierala.Fa "struct statsblob *sb" 1751a13f2e6SEdward Tomasz Napierala.Fa "int32_t voi_id" 1761a13f2e6SEdward Tomasz Napierala.Fa "enum voi_stype stype" 1771a13f2e6SEdward Tomasz Napierala.Fa "<dtype> *ret" 1781a13f2e6SEdward Tomasz Napierala.Fc 1791a13f2e6SEdward Tomasz Napierala.Ft int 1801a13f2e6SEdward Tomasz Napierala.Fo stats_blob_snapshot 1811a13f2e6SEdward Tomasz Napierala.Fa "struct statsblob **dst" 1821a13f2e6SEdward Tomasz Napierala.Fa "size_t dstmaxsz" 1831a13f2e6SEdward Tomasz Napierala.Fa "struct statsblob *src" 1841a13f2e6SEdward Tomasz Napierala.Fa "uint32_t flags" 1851a13f2e6SEdward Tomasz Napierala.Fc 1861a13f2e6SEdward Tomasz Napierala.Ft int 1871a13f2e6SEdward Tomasz Napierala.Fo stats_blob_tostr 1881a13f2e6SEdward Tomasz Napierala.Fa "struct statsblob *sb" 1891a13f2e6SEdward Tomasz Napierala.Fa "struct sbuf *buf" 1901a13f2e6SEdward Tomasz Napierala.Fa "enum sb_str_fmt fmt" 1911a13f2e6SEdward Tomasz Napierala.Fa "uint32_t flags" 1921a13f2e6SEdward Tomasz Napierala.Fc 1931a13f2e6SEdward Tomasz Napierala.Ft int 1941a13f2e6SEdward Tomasz Napierala.Fo stats_voistatdata_tostr 1951a13f2e6SEdward Tomasz Napierala.Fa "const struct voistatdata *vsd" 1961a13f2e6SEdward Tomasz Napierala.Fa "enum vsd_dtype dtype" 1971a13f2e6SEdward Tomasz Napierala.Fa "enum sb_str_fmt fmt" 1981a13f2e6SEdward Tomasz Napierala.Fa "struct sbuf *buf" 1991a13f2e6SEdward Tomasz Napierala.Fa "int objdump" 2001a13f2e6SEdward Tomasz Napierala.Fc 2011a13f2e6SEdward Tomasz Napierala.Ft typedef int 2021a13f2e6SEdward Tomasz Napierala.Fn "\*(lp*stats_blob_visitcb_t\*(rp" "struct sb_visit *sbv" "void *usrctx" 2031a13f2e6SEdward Tomasz Napierala.Ft int 2041a13f2e6SEdward Tomasz Napierala.Fo stats_blob_visit 2051a13f2e6SEdward Tomasz Napierala.Fa "struct statsblob *sb" 2061a13f2e6SEdward Tomasz Napierala.Fa "stats_blob_visitcb_t func" 2071a13f2e6SEdward Tomasz Napierala.Fa "void *usrctx" 2081a13f2e6SEdward Tomasz Napierala.Fc 2091a13f2e6SEdward Tomasz Napierala.Sh DESCRIPTION 2101a13f2e6SEdward Tomasz NapieralaThe 2111a13f2e6SEdward Tomasz Napierala.Nm 2121a13f2e6SEdward Tomasz Napieralaframework facilitates real-time kernel and user space statistics gathering. 2131a13f2e6SEdward Tomasz NapieralaThe framework is built around the 2141a13f2e6SEdward Tomasz Napierala.Dq statsblob , 2151a13f2e6SEdward Tomasz Napieralaan object embedded within a contiguous memory allocation that is mostly opaque 2161a13f2e6SEdward Tomasz Napieralato consumers and stores all required state. 2171a13f2e6SEdward Tomasz NapieralaA 2181a13f2e6SEdward Tomasz Napierala.Dq statsblob 2191a13f2e6SEdward Tomasz Napieralaobject can itself be embedded within other objects either directly or indirectly 2201a13f2e6SEdward Tomasz Napieralausing a pointer. 2211a13f2e6SEdward Tomasz Napierala.Pp 2221a13f2e6SEdward Tomasz NapieralaObjects or subsystems for which statistics are to be gathered are initialized 2231a13f2e6SEdward Tomasz Napieralafrom a template 2241a13f2e6SEdward Tomasz Napierala.Dq statsblob , 2251a13f2e6SEdward Tomasz Napieralawhich acts as the blueprint for an arbitrary set of 2261a13f2e6SEdward Tomasz NapieralaVariables Of Interest (VOIs) and their associated statistics. 2271a13f2e6SEdward Tomasz NapieralaEach template defines a schema plus associated metadata, which are kept separate 2281a13f2e6SEdward Tomasz Napieralato minimize the memory footprint of blobs. 2291a13f2e6SEdward Tomasz Napierala.Pp 2301a13f2e6SEdward Tomasz NapieralaData gathering hook functions added at appropriate locations within the code 2311a13f2e6SEdward Tomasz Napieralabase of interest feed VOI data into the framework for processing. 2321a13f2e6SEdward Tomasz Napierala.Pp 2331a13f2e6SEdward Tomasz NapieralaEach 2341a13f2e6SEdward Tomasz Napierala.Dq statsblob , 2351a13f2e6SEdward Tomasz Napieralaconsists of a 2361a13f2e6SEdward Tomasz Napierala.Vt struct statsblob 2371a13f2e6SEdward Tomasz Napieralaheader and opaque internal blob structure per the following diagram: 2381a13f2e6SEdward Tomasz Napierala.Bd -literal -offset indent 2391a13f2e6SEdward Tomasz Napierala--------------------------------------------------------- 2401a13f2e6SEdward Tomasz Napierala| struct | uint8_t | 2411a13f2e6SEdward Tomasz Napierala| statsblob | opaque[] | 2421a13f2e6SEdward Tomasz Napierala--------------------------------------------------------- 2431a13f2e6SEdward Tomasz Napierala.Ed 2441a13f2e6SEdward Tomasz Napierala.Pp 2451a13f2e6SEdward Tomasz NapieralaThe publicly visible 8-byte header is defined as: 2461a13f2e6SEdward Tomasz Napierala.Bd -literal -offset indent 2471a13f2e6SEdward Tomasz Napieralastruct statsblob { 2481a13f2e6SEdward Tomasz Napierala uint8_t abi; 2491a13f2e6SEdward Tomasz Napierala uint8_t endian; 2501a13f2e6SEdward Tomasz Napierala uint16_t flags; 2511a13f2e6SEdward Tomasz Napierala uint16_t maxsz; 2521a13f2e6SEdward Tomasz Napierala uint16_t cursz; 2531a13f2e6SEdward Tomasz Napierala uint8_t opaque[]; 2541a13f2e6SEdward Tomasz Napierala}; 2551a13f2e6SEdward Tomasz Napierala.Ed 2561a13f2e6SEdward Tomasz Napierala.Pp 2571a13f2e6SEdward Tomasz Napierala.Va abi 2581a13f2e6SEdward Tomasz Napieralaspecifies which API version the blob's 2591a13f2e6SEdward Tomasz Napierala.Va opaque 2601a13f2e6SEdward Tomasz Napieralainternals conform to 2611a13f2e6SEdward Tomasz Napierala.Pq Dv STATS_ABI_V1 is the only version currently defined . 2621a13f2e6SEdward Tomasz Napierala.Va endian 2631a13f2e6SEdward Tomasz Napieralaspecifies the endianness of the blob's fields 2641a13f2e6SEdward Tomasz Napierala.Po 2651a13f2e6SEdward Tomasz Napierala.Dv SB_LE 2661a13f2e6SEdward Tomasz Napieralafor little endian, 2671a13f2e6SEdward Tomasz Napierala.Dv SB_BE 2681a13f2e6SEdward Tomasz Napieralafor big endian, or 2691a13f2e6SEdward Tomasz Napierala.Dv SB_UE 2701a13f2e6SEdward Tomasz Napieralafor unknown endianness 2711a13f2e6SEdward Tomasz Napierala.Pc . 2721a13f2e6SEdward Tomasz Napierala.Va cursz 2731a13f2e6SEdward Tomasz Napieralaspecifies the size of the blob, while 2741a13f2e6SEdward Tomasz Napierala.Va maxsz 2751a13f2e6SEdward Tomasz Napieralaspecifies the size of the underlying memory allocation in which the 2761a13f2e6SEdward Tomasz Napieralablob is embedded. 2771a13f2e6SEdward Tomasz NapieralaBoth 2781a13f2e6SEdward Tomasz Napierala.Va cursz 2791a13f2e6SEdward Tomasz Napieralaand 2801a13f2e6SEdward Tomasz Napierala.Va maxsz 2811a13f2e6SEdward Tomasz Napieraladefault to units of bytes, unless a flag is set in 2821a13f2e6SEdward Tomasz Napierala.Va flags 2831a13f2e6SEdward Tomasz Napieralathat dictates otherwise. 2841a13f2e6SEdward Tomasz Napierala.Pp 2851a13f2e6SEdward Tomasz NapieralaTemplates are constructed by associating arbitrary VOI IDs with a set of 2861a13f2e6SEdward Tomasz Napieralastatistics, where each statistic is specified using a 2871a13f2e6SEdward Tomasz Napierala.Vt struct voistatspec 2881a13f2e6SEdward Tomasz Napieralaper the definition below: 2891a13f2e6SEdward Tomasz Napierala.Bd -literal -offset indent 2901a13f2e6SEdward Tomasz Napieralastruct voistatspec { 2911a13f2e6SEdward Tomasz Napierala vss_hlpr_fn hlpr; 2921a13f2e6SEdward Tomasz Napierala struct vss_hlpr_info *hlprinfo; 2931a13f2e6SEdward Tomasz Napierala struct voistatdata *iv; 2941a13f2e6SEdward Tomasz Napierala size_t vsdsz; 2951a13f2e6SEdward Tomasz Napierala uint32_t flags; 2961a13f2e6SEdward Tomasz Napierala enum vsd_dtype vs_dtype : 8; 2971a13f2e6SEdward Tomasz Napierala enum voi_stype stype : 8; 2981a13f2e6SEdward Tomasz Napierala}; 2991a13f2e6SEdward Tomasz Napierala.Ed 3001a13f2e6SEdward Tomasz Napierala.Pp 3011a13f2e6SEdward Tomasz NapieralaIt is generally expected that consumers will not work with 3021a13f2e6SEdward Tomasz Napierala.Vt struct voistatspec 3031a13f2e6SEdward Tomasz Napieraladirectly, and instead use the 3041a13f2e6SEdward Tomasz Napierala.Fn STATS_VSS_* 3051a13f2e6SEdward Tomasz Napieralahelper macros. 3061a13f2e6SEdward Tomasz Napierala.Pp 3071a13f2e6SEdward Tomasz NapieralaThe 3081a13f2e6SEdward Tomasz Napierala.Nm 3091a13f2e6SEdward Tomasz Napieralaframework offers the following statistics for association with VOIs: 3101a13f2e6SEdward Tomasz Napierala.Bl -tag -width ".Dv VS_STYPE_TDGST" 3111a13f2e6SEdward Tomasz Napierala.It Dv VS_STYPE_SUM 3121a13f2e6SEdward Tomasz NapieralaThe sum of VOI values. 3131a13f2e6SEdward Tomasz Napierala.It Dv VS_STYPE_MAX 3141a13f2e6SEdward Tomasz NapieralaThe maximum VOI value. 3151a13f2e6SEdward Tomasz Napierala.It Dv VS_STYPE_MIN 3161a13f2e6SEdward Tomasz NapieralaThe minimum VOI value. 3171a13f2e6SEdward Tomasz Napierala.It Dv VS_STYPE_HIST 3181a13f2e6SEdward Tomasz NapieralaA static bucket histogram of VOI values, including a count of 319*2d69f02cSGraham Percival.Dq out-of-band/bucket 3201a13f2e6SEdward Tomasz Napieralavalues which did not match any bucket. 3211a13f2e6SEdward Tomasz NapieralaHistograms can be specified as 322*2d69f02cSGraham Percival.Dq Em C Ns ontinuous Em R Ns ange 323*2d69f02cSGraham Percival.Pq CRHIST , 324*2d69f02cSGraham Percival.Dq Em D Ns iscrete Em R Ns ange 325*2d69f02cSGraham Percival.Pq DRHIST 3261a13f2e6SEdward Tomasz Napieralaor 327*2d69f02cSGraham Percival.Dq Em D Ns iscrete Em V Ns alue 328*2d69f02cSGraham Percival.Pq DVHIST , 3291a13f2e6SEdward Tomasz Napieralawith 32 or 64 bit bucket counters, depending on the VOI semantics. 3301a13f2e6SEdward Tomasz Napierala.It Dv VS_STYPE_TDGST 3311a13f2e6SEdward Tomasz NapieralaA dynamic bucket histogram of VOI values based on the t-digest method 3321a13f2e6SEdward Tomasz Napierala.Po refer to the t-digest paper in the 3331a13f2e6SEdward Tomasz Napierala.Sx SEE ALSO 3341a13f2e6SEdward Tomasz Napieralasection below 3351a13f2e6SEdward Tomasz Napierala.Pc . 3361a13f2e6SEdward Tomasz Napierala.El 3371a13f2e6SEdward Tomasz Napierala.Pp 3381a13f2e6SEdward Tomasz NapieralaA 3391a13f2e6SEdward Tomasz Napierala.Dq visitor software design pattern Ns 3401a13f2e6SEdward Tomasz Napierala-like scheme is employed to facilitate iterating over a blob's data without 3411a13f2e6SEdward Tomasz Napieralaconcern for the blob's structure. 3421a13f2e6SEdward Tomasz NapieralaThe data provided to visitor callback functions is encapsulated in 3431a13f2e6SEdward Tomasz Napierala.Vt struct sb_visit 3441a13f2e6SEdward Tomasz Napieralaper the definition below: 3451a13f2e6SEdward Tomasz Napierala.Bd -literal -offset indent 3461a13f2e6SEdward Tomasz Napieralastruct sb_visit { 3471a13f2e6SEdward Tomasz Napierala struct voistatdata *vs_data; 3481a13f2e6SEdward Tomasz Napierala uint32_t tplhash; 3491a13f2e6SEdward Tomasz Napierala uint32_t flags; 3501a13f2e6SEdward Tomasz Napierala int16_t voi_id; 3511a13f2e6SEdward Tomasz Napierala int16_t vs_dsz; 3521a13f2e6SEdward Tomasz Napierala enum vsd_dtype voi_dtype : 8; 3531a13f2e6SEdward Tomasz Napierala enum vsd_dtype vs_dtype : 8; 3541a13f2e6SEdward Tomasz Napierala int8_t vs_stype; 3551a13f2e6SEdward Tomasz Napierala uint16_t vs_errs; 3561a13f2e6SEdward Tomasz Napierala}; 3571a13f2e6SEdward Tomasz Napierala.Ed 3581a13f2e6SEdward Tomasz Napierala.Pp 3591a13f2e6SEdward Tomasz NapieralaThe 3601a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_sample_rates 3611a13f2e6SEdward Tomasz Napieralaand 3621a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_sample_rollthedice 3631a13f2e6SEdward Tomasz Napieralafunctions utilize 3641a13f2e6SEdward Tomasz Napierala.Vt struct stats_tpl_sample_rate 3651a13f2e6SEdward Tomasz Napieralato encapsulate per-template sample rate information per the definition below: 3661a13f2e6SEdward Tomasz Napierala.Bd -literal -offset indent 3671a13f2e6SEdward Tomasz Napieralastruct stats_tpl_sample_rate { 3681a13f2e6SEdward Tomasz Napierala int32_t tpl_slot_id; 3691a13f2e6SEdward Tomasz Napierala uint32_t tpl_sample_pct; 3701a13f2e6SEdward Tomasz Napierala}; 3711a13f2e6SEdward Tomasz Napierala.Ed 3721a13f2e6SEdward Tomasz Napierala.Pp 3731a13f2e6SEdward Tomasz NapieralaThe 3741a13f2e6SEdward Tomasz Napierala.Va tpl_slot_id 3751a13f2e6SEdward Tomasz Napieralamember holds the template's slot ID obtained from 3761a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_alloc 3771a13f2e6SEdward Tomasz Napieralaor 3781a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_fetch_allocid . 3791a13f2e6SEdward Tomasz NapieralaThe 3801a13f2e6SEdward Tomasz Napierala.Va tpl_sample_pct 3811a13f2e6SEdward Tomasz Napieralamember holds the template's sample rate as an integer percentage in the range 3821a13f2e6SEdward Tomasz Napierala[0,100]. 3831a13f2e6SEdward Tomasz Napierala.Pp 3841a13f2e6SEdward Tomasz NapieralaThe 3851a13f2e6SEdward Tomasz Napierala.Vt stats_tpl_sr_cb_t 3861a13f2e6SEdward Tomasz Napieralaconformant function pointer that is required as the 3871a13f2e6SEdward Tomasz Napierala.Fa arg1 3881a13f2e6SEdward Tomasz Napieralaof 3891a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_sample_rates 3901a13f2e6SEdward Tomasz Napieralais defined as: 3911a13f2e6SEdward Tomasz Napierala.Bd -literal -offset indent 3921a13f2e6SEdward Tomasz Napieralaenum stats_tpl_sr_cb_action { 3931a13f2e6SEdward Tomasz Napierala TPL_SR_UNLOCKED_GET, 3941a13f2e6SEdward Tomasz Napierala TPL_SR_RLOCKED_GET, 3951a13f2e6SEdward Tomasz Napierala TPL_SR_RUNLOCK, 3961a13f2e6SEdward Tomasz Napierala TPL_SR_PUT 3971a13f2e6SEdward Tomasz Napierala}; 3981a13f2e6SEdward Tomasz Napieralatypedef int (*stats_tpl_sr_cb_t)(enum stats_tpl_sr_cb_action action, 3991a13f2e6SEdward Tomasz Napierala struct stats_tpl_sample_rate **rates, int *nrates, void *ctx); 4001a13f2e6SEdward Tomasz Napierala.Ed 4011a13f2e6SEdward Tomasz Napierala.Pp 4021a13f2e6SEdward Tomasz NapieralaIt is required that a conformant function: 4031a13f2e6SEdward Tomasz Napierala.Bl -dash 4041a13f2e6SEdward Tomasz Napierala.It 4051a13f2e6SEdward Tomasz NapieralaReturn an appropriate 4061a13f2e6SEdward Tomasz Napierala.Xr errno 2 4071a13f2e6SEdward Tomasz Napieralaon error, otherwise 0. 4081a13f2e6SEdward Tomasz Napierala.It 4091a13f2e6SEdward Tomasz NapieralaWhen called with 4101a13f2e6SEdward Tomasz Napierala.Qq action == TPL_SR_*_GET , 4111a13f2e6SEdward Tomasz Napieralareturn the subsystem's rates list ptr and count, locked or unlocked as 4121a13f2e6SEdward Tomasz Napieralarequested. 4131a13f2e6SEdward Tomasz Napierala.It 4141a13f2e6SEdward Tomasz NapieralaWhen called with 4151a13f2e6SEdward Tomasz Napierala.Qq action == TPL_SR_RUNLOCK , 4161a13f2e6SEdward Tomasz Napieralaunlock the subsystem's rates list ptr and count. 4171a13f2e6SEdward Tomasz NapieralaPair with a prior 4181a13f2e6SEdward Tomasz Napierala.Qq action == TPL_SR_RLOCKED_GET 4191a13f2e6SEdward Tomasz Napieralacall. 4201a13f2e6SEdward Tomasz Napierala.It 4211a13f2e6SEdward Tomasz NapieralaWhen called with 4221a13f2e6SEdward Tomasz Napierala.Qq action == TPL_SR_PUT , 4231a13f2e6SEdward Tomasz Napieralaupdate the subsystem's rates list ptr and count to the sysctl processed values 4241a13f2e6SEdward Tomasz Napieralaand return the inactive list details in 4251a13f2e6SEdward Tomasz Napierala.Fa rates 4261a13f2e6SEdward Tomasz Napieralaand 4271a13f2e6SEdward Tomasz Napierala.Fa nrates 4281a13f2e6SEdward Tomasz Napieralafor garbage collection by 4291a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_sample_rates . 4301a13f2e6SEdward Tomasz Napierala.El 4311a13f2e6SEdward Tomasz Napierala.Pp 4321a13f2e6SEdward Tomasz NapieralaWhere templates need to be referenced via textual means, for example via a MIB 4331a13f2e6SEdward Tomasz Napieralavariable, the following string based template spec formats can be used: 4341a13f2e6SEdward Tomasz Napierala.Bl -enum 4351a13f2e6SEdward Tomasz Napierala.It 436*2d69f02cSGraham Percival.Qq <tplname> Ns 4371a13f2e6SEdward Tomasz Napierala:<tplhash> 4381a13f2e6SEdward Tomasz Napierala.Ns , for example 439*2d69f02cSGraham Percival.Qq TCP_DEFAULT Ns 4401a13f2e6SEdward Tomasz Napierala:1731235399 4411a13f2e6SEdward Tomasz Napierala.It 442*2d69f02cSGraham Percival.Qq <tplname> 4431a13f2e6SEdward Tomasz Napierala.Ns , for example 444*2d69f02cSGraham Percival.Qq TCP_DEFAULT 4451a13f2e6SEdward Tomasz Napierala.It 4461a13f2e6SEdward Tomasz Napierala:<tplhash> 4471a13f2e6SEdward Tomasz Napierala.Ns , for example 4481a13f2e6SEdward Tomasz Napierala:1731235399 4491a13f2e6SEdward Tomasz Napierala.El 4501a13f2e6SEdward Tomasz Napierala.Pp 4511a13f2e6SEdward Tomasz NapieralaThe first form is the normative spec format generated by the framework, while 4521a13f2e6SEdward Tomasz Napieralathe second and third forms are convenience formats primarily for user input. 4531a13f2e6SEdward Tomasz NapieralaThe use of inverted commas around the template name is optional. 4541a13f2e6SEdward Tomasz Napierala.Ss MIB Variables 4551a13f2e6SEdward Tomasz NapieralaThe in-kernel 4561a13f2e6SEdward Tomasz Napierala.Nm 4571a13f2e6SEdward Tomasz Napieralaframework exposes the following framework-specific variables in the 4581a13f2e6SEdward Tomasz Napierala.Va kern.stats 4591a13f2e6SEdward Tomasz Napieralabranch of the 4601a13f2e6SEdward Tomasz Napierala.Xr sysctl 3 4611a13f2e6SEdward Tomasz NapieralaMIB. 4621a13f2e6SEdward Tomasz Napierala.Bl -tag -width "templates" 4631a13f2e6SEdward Tomasz Napierala.It templates 4641a13f2e6SEdward Tomasz NapieralaRead-only CSV list of registered templates in normative template spec form. 4651a13f2e6SEdward Tomasz Napierala.El 4661a13f2e6SEdward Tomasz Napierala.Ss Template Management Functions 4671a13f2e6SEdward Tomasz NapieralaThe 4681a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_alloc 4691a13f2e6SEdward Tomasz Napieralafunction allocates a new template with the specified unique name and returns its 4701a13f2e6SEdward Tomasz Napieralaruntime-stable template slot ID for use with other API functions. 4711a13f2e6SEdward Tomasz NapieralaThe 4721a13f2e6SEdward Tomasz Napierala.Fa flags 4731a13f2e6SEdward Tomasz Napieralaargument is currently unused. 4741a13f2e6SEdward Tomasz Napierala.Pp 4751a13f2e6SEdward Tomasz NapieralaThe 4761a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_fetch_allocid 4771a13f2e6SEdward Tomasz Napieralafunction returns the runtime-stable template slot ID of any registered template 4781a13f2e6SEdward Tomasz Napieralamatching the specified name and hash. 4791a13f2e6SEdward Tomasz Napierala.Pp 4801a13f2e6SEdward Tomasz NapieralaThe 4811a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_fetch 4821a13f2e6SEdward Tomasz Napieralafunction returns the pointer to the registered template object at the specified 4831a13f2e6SEdward Tomasz Napieralatemplate slot ID. 4841a13f2e6SEdward Tomasz Napierala.Pp 4851a13f2e6SEdward Tomasz NapieralaThe 4861a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_id2name 4871a13f2e6SEdward Tomasz Napieralafunction returns the name of the registered template object at the specified 4881a13f2e6SEdward Tomasz Napieralatemplate slot ID. 4891a13f2e6SEdward Tomasz Napierala.Pp 4901a13f2e6SEdward Tomasz NapieralaThe 4911a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_sample_rates 4921a13f2e6SEdward Tomasz Napieralafunction provides a generic handler for template sample rates management and 4931a13f2e6SEdward Tomasz Napieralareporting via 4941a13f2e6SEdward Tomasz Napierala.Xr sysctl 3 4951a13f2e6SEdward Tomasz NapieralaMIB variables. 4961a13f2e6SEdward Tomasz NapieralaSubsystems can use this function to create a subsystem-specific 4971a13f2e6SEdward Tomasz Napierala.Xr SYSCTL_PROC 9 4981a13f2e6SEdward Tomasz NapieralaMIB variable that manages and reports subsystem-specific template sampling 4991a13f2e6SEdward Tomasz Napieralarates. 5001a13f2e6SEdward Tomasz NapieralaSubsystems must supply a 5011a13f2e6SEdward Tomasz Napierala.Vt stats_tpl_sr_cb_t 5021a13f2e6SEdward Tomasz Napieralaconformant function pointer as the sysctl's 5031a13f2e6SEdward Tomasz Napierala.Fa arg1 , 5041a13f2e6SEdward Tomasz Napieralawhich is a callback used to interact with the subsystem's stats template sample 5051a13f2e6SEdward Tomasz Napieralarates list. 5061a13f2e6SEdward Tomasz NapieralaSubsystems can optionally specify the sysctl's 5071a13f2e6SEdward Tomasz Napierala.Fa arg2 5081a13f2e6SEdward Tomasz Napieralaas non-zero, which causes a zero-initialized allocation of arg2-sized contextual 5091a13f2e6SEdward Tomasz Napieralamemory to be heap-allocated and passed in to all subsystem callbacks made during 5101a13f2e6SEdward Tomasz Napieralathe operation of 5111a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_sample_rates . 5121a13f2e6SEdward Tomasz Napierala.Pp 5131a13f2e6SEdward Tomasz NapieralaThe 5141a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_sample_rollthedice 5151a13f2e6SEdward Tomasz Napieralafunction makes a weighted random template selection from the supplied array of 5161a13f2e6SEdward Tomasz Napieralatemplate sampling rates. 5171a13f2e6SEdward Tomasz NapieralaThe cumulative percentage of all sampling rates should not exceed 100. 5181a13f2e6SEdward Tomasz NapieralaIf no seed is supplied, a PRNG is used to generate a true random number so that 5191a13f2e6SEdward Tomasz Napieralaevery selection is independent. 5201a13f2e6SEdward Tomasz NapieralaIf a seed is supplied, selection will be made randomly across different seeds, but 5211a13f2e6SEdward Tomasz Napieraladeterministically given the same seed. 5221a13f2e6SEdward Tomasz Napierala.Pp 5231a13f2e6SEdward Tomasz NapieralaThe 5241a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_add_voistats 5251a13f2e6SEdward Tomasz Napieralafunction is used to add a VOI and associated set of statistics to the registered 5261a13f2e6SEdward Tomasz Napieralatemplate object at the specified template slot ID. 5271a13f2e6SEdward Tomasz NapieralaThe set of statistics is passed as an array of 5281a13f2e6SEdward Tomasz Napierala.Vt struct voistatspec 5291a13f2e6SEdward Tomasz Napieralawhich can be initialized using the 5301a13f2e6SEdward Tomasz Napierala.Fn STATS_VSS_* 5311a13f2e6SEdward Tomasz Napieralahelper macros or manually for non-standard use cases. 5321a13f2e6SEdward Tomasz NapieralaFor static 5331a13f2e6SEdward Tomasz Napierala.Fa vss 5341a13f2e6SEdward Tomasz Napieralaarrays, the 5351a13f2e6SEdward Tomasz Napierala.Fa nvss 5361a13f2e6SEdward Tomasz Napieralacount of array elements can be determined by passing 5371a13f2e6SEdward Tomasz Napierala.Fa vss 5381a13f2e6SEdward Tomasz Napieralato the 5391a13f2e6SEdward Tomasz Napierala.Fn NVSS 5401a13f2e6SEdward Tomasz Napieralamacro. 5411a13f2e6SEdward Tomasz NapieralaThe 5421a13f2e6SEdward Tomasz Napierala.Dv SB_VOI_RELUPDATE 5431a13f2e6SEdward Tomasz Napieralaflag can be passed to configure the VOI for use with 5441a13f2e6SEdward Tomasz Napierala.Fn stats_voi_update_rel_<dtype> , 5451a13f2e6SEdward Tomasz Napieralawhich entails maintaining an extra 8 bytes of state in the blob at each update. 5461a13f2e6SEdward Tomasz Napierala.Ss Data Gathering Functions 5471a13f2e6SEdward Tomasz NapieralaThe 5481a13f2e6SEdward Tomasz Napierala.Fn stats_voi_update_abs_<dtype> 5491a13f2e6SEdward Tomasz Napieralaand 5501a13f2e6SEdward Tomasz Napierala.Fn stats_voi_update_rel_<dtype> 5511a13f2e6SEdward Tomasz Napieralafunctions both update all the statistics associated with the VOI identified by 5521a13f2e6SEdward Tomasz Napierala.Fa voi_id . 5531a13f2e6SEdward Tomasz NapieralaThe 5541a13f2e6SEdward Tomasz Napierala.Dq abs 5551a13f2e6SEdward Tomasz Napieralacall uses 5561a13f2e6SEdward Tomasz Napierala.Fa voival 5571a13f2e6SEdward Tomasz Napieralaas an absolute value, whereas the 5581a13f2e6SEdward Tomasz Napierala.Dq rel 5591a13f2e6SEdward Tomasz Napieralacall uses 5601a13f2e6SEdward Tomasz Napierala.Fa voival 5611a13f2e6SEdward Tomasz Napieralaas a value relative to that of the previous update function call, by adding it 5621a13f2e6SEdward Tomasz Napieralato the previous value and using the result for the update. 5631a13f2e6SEdward Tomasz NapieralaRelative updates are only possible for VOIs that were added to the template with 5641a13f2e6SEdward Tomasz Napieralathe 5651a13f2e6SEdward Tomasz Napierala.Dv SB_VOI_RELUPDATE 5661a13f2e6SEdward Tomasz Napieralaflag specified to 5671a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_add_voistats . 5681a13f2e6SEdward Tomasz Napierala.Ss Utility Functions 5691a13f2e6SEdward Tomasz NapieralaThe 5701a13f2e6SEdward Tomasz Napierala.Fn stats_blob_alloc 5711a13f2e6SEdward Tomasz Napieralafunction allocates and initializes a new blob based on the registered template 5721a13f2e6SEdward Tomasz Napieralaobject at the specified template slot ID. 5731a13f2e6SEdward Tomasz Napierala.Pp 5741a13f2e6SEdward Tomasz NapieralaThe 5751a13f2e6SEdward Tomasz Napierala.Fn stats_blob_init 5761a13f2e6SEdward Tomasz Napieralafunction initializes a new blob in an existing memory allocation based on the 5771a13f2e6SEdward Tomasz Napieralaregistered template object at the specified template slot ID. 5781a13f2e6SEdward Tomasz Napierala.Pp 5791a13f2e6SEdward Tomasz NapieralaThe 5801a13f2e6SEdward Tomasz Napierala.Fn stats_blob_clone 5811a13f2e6SEdward Tomasz Napieralafunction duplicates the 5821a13f2e6SEdward Tomasz Napierala.Fa src 5831a13f2e6SEdward Tomasz Napieralablob into 5841a13f2e6SEdward Tomasz Napierala.Fa dst , 5851a13f2e6SEdward Tomasz Napieralaleaving only the 5861a13f2e6SEdward Tomasz Napierala.Va maxsz 5871a13f2e6SEdward Tomasz Napieralafield of 5881a13f2e6SEdward Tomasz Napierala.Fa dst 5891a13f2e6SEdward Tomasz Napieralauntouched. 5901a13f2e6SEdward Tomasz NapieralaThe 5911a13f2e6SEdward Tomasz Napierala.Dv SB_CLONE_ALLOCDST 5921a13f2e6SEdward Tomasz Napieralaflag can be passed to instruct the function to allocate a new blob of 5931a13f2e6SEdward Tomasz Napieralaappropriate size into which to clone 5941a13f2e6SEdward Tomasz Napierala.Fa src , 5951a13f2e6SEdward Tomasz Napieralastoring the new pointer in 5961a13f2e6SEdward Tomasz Napierala.Fa *dst . 5971a13f2e6SEdward Tomasz NapieralaThe 5981a13f2e6SEdward Tomasz Napierala.Dv SB_CLONE_USRDSTNOFAULT 5991a13f2e6SEdward Tomasz Napieralaor 6001a13f2e6SEdward Tomasz Napierala.Dv SB_CLONE_USRDST 6011a13f2e6SEdward Tomasz Napieralaflags can be set to respectively signal that 6021a13f2e6SEdward Tomasz Napierala.Xr copyout_nofault 9 6031a13f2e6SEdward Tomasz Napieralaor 6041a13f2e6SEdward Tomasz Napierala.Xr copyout 9 6051a13f2e6SEdward Tomasz Napieralashould be used because 6061a13f2e6SEdward Tomasz Napierala.Fa *dst 6071a13f2e6SEdward Tomasz Napieralais a user space address. 6081a13f2e6SEdward Tomasz Napierala.Pp 6091a13f2e6SEdward Tomasz NapieralaThe 6101a13f2e6SEdward Tomasz Napierala.Fn stats_blob_snapshot 6111a13f2e6SEdward Tomasz Napieralafunction calls 6121a13f2e6SEdward Tomasz Napierala.Fn stats_blob_clone 6131a13f2e6SEdward Tomasz Napieralato obtain a copy of 6141a13f2e6SEdward Tomasz Napierala.Fa src 6151a13f2e6SEdward Tomasz Napieralaand then performs any additional functions required to produce a coherent 6161a13f2e6SEdward Tomasz Napieralablob snapshot. 6171a13f2e6SEdward Tomasz NapieralaThe flags interpreted by 6181a13f2e6SEdward Tomasz Napierala.Fn stats_blob_clone 6191a13f2e6SEdward Tomasz Napieralaalso apply to 6201a13f2e6SEdward Tomasz Napierala.Fn stats_blob_snapshot . 6211a13f2e6SEdward Tomasz NapieralaAdditionally, the 6221a13f2e6SEdward Tomasz Napierala.Dv SB_CLONE_RSTSRC 6231a13f2e6SEdward Tomasz Napieralaflag can be used to effect a reset of the 6241a13f2e6SEdward Tomasz Napierala.Fa src 6251a13f2e6SEdward Tomasz Napieralablob's statistics after a snapshot is successfully taken. 6261a13f2e6SEdward Tomasz Napierala.Pp 6271a13f2e6SEdward Tomasz NapieralaThe 6281a13f2e6SEdward Tomasz Napierala.Fn stats_blob_destroy 6291a13f2e6SEdward Tomasz Napieralafunction destroys a blob previously created with 6301a13f2e6SEdward Tomasz Napierala.Fn stats_blob_alloc , 6311a13f2e6SEdward Tomasz Napierala.Fn stats_blob_clone 6321a13f2e6SEdward Tomasz Napieralaor 6331a13f2e6SEdward Tomasz Napierala.Fn stats_blob_snapshot . 6341a13f2e6SEdward Tomasz Napierala.Pp 6351a13f2e6SEdward Tomasz NapieralaThe 6361a13f2e6SEdward Tomasz Napierala.Fn stats_blob_visit 6371a13f2e6SEdward Tomasz Napieralafunction allows the caller to iterate over the contents of a blob. 6381a13f2e6SEdward Tomasz NapieralaThe callback function 6391a13f2e6SEdward Tomasz Napierala.Fa func 6401a13f2e6SEdward Tomasz Napieralais called for every VOI and statistic in the blob, passing a 6411a13f2e6SEdward Tomasz Napierala.Vt struct sb_visit 6421a13f2e6SEdward Tomasz Napieralaand the user context argument 6431a13f2e6SEdward Tomasz Napierala.Fa usrctx 6441a13f2e6SEdward Tomasz Napieralato the callback function. 6451a13f2e6SEdward Tomasz NapieralaThe 6461a13f2e6SEdward Tomasz Napierala.Fa sbv 6471a13f2e6SEdward Tomasz Napieralapassed to the callback function may have one or more of the following flags set 6481a13f2e6SEdward Tomasz Napieralain the 6491a13f2e6SEdward Tomasz Napierala.Va flags 6501a13f2e6SEdward Tomasz Napieralastruct member to provide useful metadata about the iteration: 6511a13f2e6SEdward Tomasz Napierala.Dv SB_IT_FIRST_CB , 6521a13f2e6SEdward Tomasz Napierala.Dv SB_IT_LAST_CB , 6531a13f2e6SEdward Tomasz Napierala.Dv SB_IT_FIRST_VOI , 6541a13f2e6SEdward Tomasz Napierala.Dv SB_IT_LAST_VOI , 6551a13f2e6SEdward Tomasz Napierala.Dv SB_IT_FIRST_VOISTAT , 6561a13f2e6SEdward Tomasz Napierala.Dv SB_IT_LAST_VOISTAT , 6571a13f2e6SEdward Tomasz Napierala.Dv SB_IT_NULLVOI 6581a13f2e6SEdward Tomasz Napieralaand 6591a13f2e6SEdward Tomasz Napierala.Dv SB_IT_NULLVOISTAT . 6601a13f2e6SEdward Tomasz NapieralaReturning a non-zero value from the callback function terminates the iteration. 6611a13f2e6SEdward Tomasz Napierala.Pp 6621a13f2e6SEdward Tomasz NapieralaThe 6631a13f2e6SEdward Tomasz Napierala.Fn stats_blob_tostr 6641a13f2e6SEdward Tomasz Napieralarenders a string representation of a blob into the 6651a13f2e6SEdward Tomasz Napierala.Xr sbuf 9 6661a13f2e6SEdward Tomasz Napierala.Fa buf . 6671a13f2e6SEdward Tomasz NapieralaCurrently supported render formats are 6681a13f2e6SEdward Tomasz Napierala.Dv SB_STRFMT_FREEFORM 6691a13f2e6SEdward Tomasz Napieralaand 6701a13f2e6SEdward Tomasz Napierala.Dv SB_STRFMT_JSON . 6711a13f2e6SEdward Tomasz NapieralaThe 6721a13f2e6SEdward Tomasz Napierala.Dv SB_TOSTR_OBJDUMP 6731a13f2e6SEdward Tomasz Napieralaflag can be passed to render version specific opaque implementation detail for 6741a13f2e6SEdward Tomasz Napieraladebugging or string-to-binary blob reconstruction purposes. 6751a13f2e6SEdward Tomasz NapieralaThe 6761a13f2e6SEdward Tomasz Napierala.Dv SB_TOSTR_META 6771a13f2e6SEdward Tomasz Napieralaflag can be passed to render template metadata into the string representation, 6781a13f2e6SEdward Tomasz Napieralausing the blob's template hash to lookup the corresponding template. 6791a13f2e6SEdward Tomasz Napierala.Pp 6801a13f2e6SEdward Tomasz NapieralaThe 6811a13f2e6SEdward Tomasz Napierala.Fn stats_voistatdata_tostr 6821a13f2e6SEdward Tomasz Napieralarenders a string representation of an individual statistic's data into the 6831a13f2e6SEdward Tomasz Napierala.Xr sbuf 9 6841a13f2e6SEdward Tomasz Napierala.Fa buf . 6851a13f2e6SEdward Tomasz NapieralaThe same render formats supported by the 6861a13f2e6SEdward Tomasz Napierala.Fn stats_blob_tostr 6871a13f2e6SEdward Tomasz Napieralafunction can be specified, and the 6881a13f2e6SEdward Tomasz Napierala.Fa objdump 6891a13f2e6SEdward Tomasz Napieralaboolean has the same meaning as the 6901a13f2e6SEdward Tomasz Napierala.Dv SB_TOSTR_OBJDUMP 6911a13f2e6SEdward Tomasz Napieralaflag. 6921a13f2e6SEdward Tomasz Napierala.Pp 6931a13f2e6SEdward Tomasz NapieralaThe 6941a13f2e6SEdward Tomasz Napierala.Fn stats_voistat_fetch_dptr 6951a13f2e6SEdward Tomasz Napieralafunction returns an internal blob pointer to the specified 6961a13f2e6SEdward Tomasz Napierala.Fa stype 6971a13f2e6SEdward Tomasz Napieralastatistic data for the VOI 6981a13f2e6SEdward Tomasz Napierala.Fa voi_id . 6991a13f2e6SEdward Tomasz NapieralaThe 7001a13f2e6SEdward Tomasz Napierala.Fn stats_voistat_fetch_<dtype> 7011a13f2e6SEdward Tomasz Napieralafunctions are convenience wrappers around 7021a13f2e6SEdward Tomasz Napierala.Fn stats_voistat_fetch_dptr 7031a13f2e6SEdward Tomasz Napieralato perform the extraction for simple data types. 7041a13f2e6SEdward Tomasz Napierala.Sh IMPLEMENTATION NOTES 7051a13f2e6SEdward Tomasz NapieralaThe following notes apply to STATS_ABI_V1 format statsblobs. 7061a13f2e6SEdward Tomasz Napierala.Ss Space-Time Complexity 7071a13f2e6SEdward Tomasz NapieralaBlobs are laid out as three distinct memory regions following the header: 7081a13f2e6SEdward Tomasz Napierala.Bd -literal -offset indent 7091a13f2e6SEdward Tomasz Napierala------------------------------------------------------ 7101a13f2e6SEdward Tomasz Napierala| struct | struct | struct | struct | 7111a13f2e6SEdward Tomasz Napierala| statsblobv1 | voi [] | voistat [] | voistatdata [] | 7121a13f2e6SEdward Tomasz Napierala------------------------------------------------------ 7131a13f2e6SEdward Tomasz Napierala.Ed 7141a13f2e6SEdward Tomasz Napierala.Pp 7151a13f2e6SEdward Tomasz NapieralaBlobs store VOI and statistic blob state 7161a13f2e6SEdward Tomasz Napierala.Po 7171a13f2e6SEdward Tomasz Napierala8 bytes for 7181a13f2e6SEdward Tomasz Napierala.Vt struct voi 7191a13f2e6SEdward Tomasz Napieralaand 8 bytes for 7201a13f2e6SEdward Tomasz Napierala.Vt struct voistat 7211a13f2e6SEdward Tomasz Napieralarespectively 7221a13f2e6SEdward Tomasz Napierala.Pc 7231a13f2e6SEdward Tomasz Napieralain sparse arrays, using the 7241a13f2e6SEdward Tomasz Napierala.Fa voi_id 7251a13f2e6SEdward Tomasz Napieralaand 7261a13f2e6SEdward Tomasz Napierala.Vt enum voi_stype 7271a13f2e6SEdward Tomasz Napieralaas array indices. 7281a13f2e6SEdward Tomasz NapieralaThis allows O(1) access to any voi/voistat pair in the blob, at the expense of 7291a13f2e6SEdward Tomasz Napierala8 bytes of wasted memory per vacant slot for templates which do not specify 7301a13f2e6SEdward Tomasz Napieralacontiguously numbered VOIs and/or statistic types. 7311a13f2e6SEdward Tomasz NapieralaData storage for statistics is only allocated for non-vacant slot pairs. 7321a13f2e6SEdward Tomasz Napierala.Pp 7331a13f2e6SEdward Tomasz NapieralaTo provide a concrete example, a blob with the following specification: 7341a13f2e6SEdward Tomasz Napierala.Bl -dash 7351a13f2e6SEdward Tomasz Napierala.It 7361a13f2e6SEdward Tomasz NapieralaTwo VOIs; ID 0 and 2; added to the template in that order 7371a13f2e6SEdward Tomasz Napierala.It 7381a13f2e6SEdward Tomasz NapieralaVOI 0 is of data type 7391a13f2e6SEdward Tomasz Napierala.Vt int64_t , 7401a13f2e6SEdward Tomasz Napieralais configured with 7411a13f2e6SEdward Tomasz Napierala.Dv SB_VOI_RELUPDATE 7421a13f2e6SEdward Tomasz Napieralato enable support for relative updates using 7431a13f2e6SEdward Tomasz Napierala.Fn stats_voi_update_rel_<dtype> , 7441a13f2e6SEdward Tomasz Napieralaand has a 7451a13f2e6SEdward Tomasz Napierala.Dv VS_STYPE_MIN 7461a13f2e6SEdward Tomasz Napieralastatistic associated with it. 7471a13f2e6SEdward Tomasz Napierala.It 7481a13f2e6SEdward Tomasz NapieralaVOI 2 is of data type 7491a13f2e6SEdward Tomasz Napierala.Vt uint32_t 7501a13f2e6SEdward Tomasz Napieralawith 7511a13f2e6SEdward Tomasz Napierala.Dv VS_STYPE_SUM 7521a13f2e6SEdward Tomasz Napieralaand 7531a13f2e6SEdward Tomasz Napierala.Dv VS_STYPE_MAX 7541a13f2e6SEdward Tomasz Napieralastatistics associated with it. 7551a13f2e6SEdward Tomasz Napierala.El 7561a13f2e6SEdward Tomasz Napierala.Pp 7571a13f2e6SEdward Tomasz Napieralawould have the following memory layout: 7581a13f2e6SEdward Tomasz Napierala.Bd -literal 7591a13f2e6SEdward Tomasz Napierala-------------------------------------- 7601a13f2e6SEdward Tomasz Napierala| header | struct statsblobv1, 32 bytes 7611a13f2e6SEdward Tomasz Napierala|------------------------------------| 7621a13f2e6SEdward Tomasz Napierala| voi[0] | struct voi, 8 bytes 7631a13f2e6SEdward Tomasz Napierala| voi[1] (vacant) | struct voi, 8 bytes 7641a13f2e6SEdward Tomasz Napierala| voi[2] | struct voi, 8 bytes 7651a13f2e6SEdward Tomasz Napierala|------------------------------------| 7661a13f2e6SEdward Tomasz Napierala| voi[2]voistat[VOISTATE] (vacant) | struct voistat, 8 bytes 7671a13f2e6SEdward Tomasz Napierala| voi[2]voistat[SUM] | struct voistat, 8 bytes 7681a13f2e6SEdward Tomasz Napierala| voi[2]voistat[MAX] | struct voistat, 8 bytes 7691a13f2e6SEdward Tomasz Napierala| voi[0]voistat[VOISTATE] | struct voistat, 8 bytes 7701a13f2e6SEdward Tomasz Napierala| voi[0]voistat[SUM] (vacant) | struct voistat, 8 bytes 7711a13f2e6SEdward Tomasz Napierala| voi[0]voistat[MAX] (vacant) | struct voistat, 8 bytes 7721a13f2e6SEdward Tomasz Napierala| voi[0]voistat[MIN] | struct voistat, 8 bytes 7731a13f2e6SEdward Tomasz Napierala|------------------------------------| 7741a13f2e6SEdward Tomasz Napierala| voi[2]voistat[SUM]voistatdata | struct voistatdata_int32, 4 bytes 7751a13f2e6SEdward Tomasz Napierala| voi[2]voistat[MAX]voistatdata | struct voistatdata_int32, 4 bytes 7761a13f2e6SEdward Tomasz Napierala| voi[0]voistat[VOISTATE]voistatdata | struct voistatdata_numeric, 8 bytes 7771a13f2e6SEdward Tomasz Napierala| voi[0]voistat[MIN]voistatdata | struct voistatdata_int64, 8 bytes 7781a13f2e6SEdward Tomasz Napierala-------------------------------------- 7791a13f2e6SEdward Tomasz Napierala TOTAL 136 bytes 7801a13f2e6SEdward Tomasz Napierala.Ed 7811a13f2e6SEdward Tomasz Napierala.Pp 7821a13f2e6SEdward Tomasz NapieralaWhen rendered to string format using 7831a13f2e6SEdward Tomasz Napierala.Fn stats_blob_tostr , 7841a13f2e6SEdward Tomasz Napieralathe 7851a13f2e6SEdward Tomasz Napierala.Dv SB_STRFMT_FREEFORM 7861a13f2e6SEdward Tomasz Napierala.Fa fmt 7871a13f2e6SEdward Tomasz Napieralaand the 7881a13f2e6SEdward Tomasz Napierala.Dv SB_TOSTR_OBJDUMP 7891a13f2e6SEdward Tomasz Napieralaflag, the rendered output is: 7901a13f2e6SEdward Tomasz Napierala.Bd -literal 7911a13f2e6SEdward Tomasz Napieralastruct statsblobv1@0x8016250a0, abi=1, endian=1, maxsz=136, cursz=136, \\ 7921a13f2e6SEdward Tomasz Napierala created=6294158585626144, lastrst=6294158585626144, flags=0x0000, \\ 7931a13f2e6SEdward Tomasz Napierala stats_off=56, statsdata_off=112, tplhash=2994056564 7941a13f2e6SEdward Tomasz Napierala vois[0]: id=0, name="", flags=0x0001, dtype=INT_S64, voistatmaxid=3, \\ 7951a13f2e6SEdward Tomasz Napierala stats_off=80 7961a13f2e6SEdward Tomasz Napierala vois[0]stat[0]: stype=VOISTATE, flags=0x0000, dtype=VOISTATE, \\ 7971a13f2e6SEdward Tomasz Napierala dsz=8, data_off=120 7981a13f2e6SEdward Tomasz Napierala voistatdata: prev=0 7991a13f2e6SEdward Tomasz Napierala vois[0]stat[1]: stype=-1 8001a13f2e6SEdward Tomasz Napierala vois[0]stat[2]: stype=-1 8011a13f2e6SEdward Tomasz Napierala vois[0]stat[3]: stype=MIN, flags=0x0000, dtype=INT_S64, \\ 8021a13f2e6SEdward Tomasz Napierala dsz=8, data_off=128 8031a13f2e6SEdward Tomasz Napierala voistatdata: 9223372036854775807 8041a13f2e6SEdward Tomasz Napierala vois[1]: id=-1 8051a13f2e6SEdward Tomasz Napierala vois[2]: id=2, name="", flags=0x0000, dtype=INT_U32, voistatmaxid=2, \\ 8061a13f2e6SEdward Tomasz Napierala stats_off=56 8071a13f2e6SEdward Tomasz Napierala vois[2]stat[0]: stype=-1 8081a13f2e6SEdward Tomasz Napierala vois[2]stat[1]: stype=SUM, flags=0x0000, dtype=INT_U32, dsz=4, \\ 8091a13f2e6SEdward Tomasz Napierala data_off=112 8101a13f2e6SEdward Tomasz Napierala voistatdata: 0 8111a13f2e6SEdward Tomasz Napierala vois[2]stat[2]: stype=MAX, flags=0x0000, dtype=INT_U32, dsz=4, \\ 8121a13f2e6SEdward Tomasz Napierala data_off=116 8131a13f2e6SEdward Tomasz Napierala voistatdata: 0 8141a13f2e6SEdward Tomasz Napierala.Ed 8151a13f2e6SEdward Tomasz Napierala.Pp 8161a13f2e6SEdward Tomasz NapieralaNote: The 8171a13f2e6SEdward Tomasz Napierala.Qq \e 8181a13f2e6SEdward Tomasz Napieralapresent in the rendered output above indicates a manual line break inserted to 8191a13f2e6SEdward Tomasz Napieralakeep the man page within 80 columns and is not part of the actual output. 8201a13f2e6SEdward Tomasz Napierala.Ss Locking 8211a13f2e6SEdward Tomasz NapieralaThe 8221a13f2e6SEdward Tomasz Napierala.Nm 8231a13f2e6SEdward Tomasz Napieralaframework does not provide any concurrency protection at the individual blob 8241a13f2e6SEdward Tomasz Napieralalevel, instead requiring that consumers guarantee mutual exclusion when calling 8251a13f2e6SEdward Tomasz NapieralaAPI functions that reference a non-template blob. 8261a13f2e6SEdward Tomasz Napierala.Pp 8271a13f2e6SEdward Tomasz NapieralaThe list of templates is protected with a 8281a13f2e6SEdward Tomasz Napierala.Xr rwlock 9 8291a13f2e6SEdward Tomasz Napieralain-kernel, and 8301a13f2e6SEdward Tomasz Napierala.Xr pthread 3 8311a13f2e6SEdward Tomasz Napieralarw lock in user space to support concurrency between template management and 8321a13f2e6SEdward Tomasz Napieralablob initialization operations. 8331a13f2e6SEdward Tomasz Napierala.Sh RETURN VALUES 8341a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_alloc 8351a13f2e6SEdward Tomasz Napieralareturns a runtime-stable template slot ID on success, or a negative errno on 8361a13f2e6SEdward Tomasz Napieralafailure. 8371a13f2e6SEdward Tomasz Napierala-EINVAL is returned if any problems are detected with the arguments. 8381a13f2e6SEdward Tomasz Napierala-EEXIST is returned if an existing template is registered with the same name. 8391a13f2e6SEdward Tomasz Napierala-ENOMEM is returned if a required memory allocation fails. 8401a13f2e6SEdward Tomasz Napierala.Pp 8411a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_fetch_allocid 8421a13f2e6SEdward Tomasz Napieralareturns a runtime-stable template slot ID, or negative errno on failure. 8431a13f2e6SEdward Tomasz Napierala-ESRCH is returned if no registered template matches the specified name and/or 8441a13f2e6SEdward Tomasz Napieralahash. 8451a13f2e6SEdward Tomasz Napierala.Pp 8461a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_fetch 8471a13f2e6SEdward Tomasz Napieralareturns 0 on success, or ENOENT if an invalid 8481a13f2e6SEdward Tomasz Napierala.Fa tpl_id 8491a13f2e6SEdward Tomasz Napieralais specified. 8501a13f2e6SEdward Tomasz Napierala.Pp 8511a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_id2name 8521a13f2e6SEdward Tomasz Napieralareturns 0 on success, or an errno on failure. 8531a13f2e6SEdward Tomasz NapieralaEOVERFLOW is returned if the length of 8541a13f2e6SEdward Tomasz Napierala.Fa buf 8551a13f2e6SEdward Tomasz Napieralaspecified by 8561a13f2e6SEdward Tomasz Napierala.Fa len 8571a13f2e6SEdward Tomasz Napieralais too short to hold the template's name. 8581a13f2e6SEdward Tomasz NapieralaENOENT is returned if an invalid 8591a13f2e6SEdward Tomasz Napierala.Fa tpl_id 8601a13f2e6SEdward Tomasz Napieralais specified. 8611a13f2e6SEdward Tomasz Napierala.Pp 8621a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_sample_rollthedice 8631a13f2e6SEdward Tomasz Napieralareturns a valid template slot id selected from 8641a13f2e6SEdward Tomasz Napierala.Fa rates 8651a13f2e6SEdward Tomasz Napieralaor -1 if a NULL selection was made, that is no stats collection this roll. 8661a13f2e6SEdward Tomasz Napierala.Pp 8671a13f2e6SEdward Tomasz Napierala.Fn stats_tpl_add_voistats 8681a13f2e6SEdward Tomasz Napieralareturn 0 on success, or an errno on failure. 8691a13f2e6SEdward Tomasz NapieralaEINVAL is returned if any problems are detected with the arguments. 8701a13f2e6SEdward Tomasz NapieralaEFBIG is returned if the resulting blob would have exceeded the maximum size. 8711a13f2e6SEdward Tomasz NapieralaEOPNOTSUPP is returned if an attempt is made to add more VOI stats to a 8721a13f2e6SEdward Tomasz Napieralapreviously configured VOI. 8731a13f2e6SEdward Tomasz NapieralaENOMEM is returned if a required memory allocation fails. 8741a13f2e6SEdward Tomasz Napierala.Pp 8751a13f2e6SEdward Tomasz Napierala.Fn stats_voi_update_abs_<dtype> 8761a13f2e6SEdward Tomasz Napieralaand 8771a13f2e6SEdward Tomasz Napierala.Fn stats_voi_update_rel_<dtype> 8781a13f2e6SEdward Tomasz Napieralareturn 0 on success, or EINVAL if any problems are detected with the arguments. 8791a13f2e6SEdward Tomasz Napierala.Pp 8801a13f2e6SEdward Tomasz Napierala.Fn stats_blob_init 8811a13f2e6SEdward Tomasz Napieralareturns 0 on success, or an errno on failure. 8821a13f2e6SEdward Tomasz NapieralaEINVAL is returned if any problems are detected with the arguments. 8831a13f2e6SEdward Tomasz NapieralaEOVERFLOW is returned if the template blob's 8841a13f2e6SEdward Tomasz Napierala.Fa cursz 8851a13f2e6SEdward Tomasz Napieralais larger than the 8861a13f2e6SEdward Tomasz Napierala.Fa maxsz 8871a13f2e6SEdward Tomasz Napieralaof the blob being initialized. 8881a13f2e6SEdward Tomasz Napierala.Pp 8891a13f2e6SEdward Tomasz Napierala.Fn stats_blob_alloc 8901a13f2e6SEdward Tomasz Napieralareturns a pointer to a newly allocated and initialized blob based on the 8911a13f2e6SEdward Tomasz Napieralaspecified template with slot ID 8921a13f2e6SEdward Tomasz Napierala.Fa tpl_id , 8931a13f2e6SEdward Tomasz Napieralaor NULL if the memory allocation failed. 8941a13f2e6SEdward Tomasz Napierala.Pp 8951a13f2e6SEdward Tomasz Napierala.Fn stats_blob_clone 8961a13f2e6SEdward Tomasz Napieralaand 8971a13f2e6SEdward Tomasz Napierala.Fn stats_blob_snapshot 8981a13f2e6SEdward Tomasz Napieralareturn 0 on success, or an errno on failure. 8991a13f2e6SEdward Tomasz NapieralaEINVAL is returned if any problems are detected with the arguments. 9001a13f2e6SEdward Tomasz NapieralaENOMEM is returned if the SB_CLONE_ALLOCDST flag was specified and the memory 9011a13f2e6SEdward Tomasz Napieralaallocation for 9021a13f2e6SEdward Tomasz Napierala.Fa dst 9031a13f2e6SEdward Tomasz Napieralafails. 9041a13f2e6SEdward Tomasz NapieralaEOVERFLOW is returned if the src blob's 9051a13f2e6SEdward Tomasz Napierala.Fa cursz 9061a13f2e6SEdward Tomasz Napieralais larger than the 9071a13f2e6SEdward Tomasz Napierala.Fa maxsz 9081a13f2e6SEdward Tomasz Napieralaof the 9091a13f2e6SEdward Tomasz Napierala.Fa dst 9101a13f2e6SEdward Tomasz Napieralablob. 9111a13f2e6SEdward Tomasz Napierala.Pp 9121a13f2e6SEdward Tomasz Napierala.Fn stats_blob_visit 9131a13f2e6SEdward Tomasz Napieralareturns 0 on success, or EINVAL if any problems are detected with the arguments. 9141a13f2e6SEdward Tomasz Napierala.Pp 9151a13f2e6SEdward Tomasz Napierala.Fn stats_blob_tostr 9161a13f2e6SEdward Tomasz Napieralaand 9171a13f2e6SEdward Tomasz Napierala.Fn stats_voistatdata_tostr 9181a13f2e6SEdward Tomasz Napieralareturn 0 on success, or an errno on failure. 9191a13f2e6SEdward Tomasz NapieralaEINVAL is returned if any problems are detected with the arguments, otherwise 9201a13f2e6SEdward Tomasz Napieralaany error returned by 9211a13f2e6SEdward Tomasz Napierala.Fn sbuf_error 9221a13f2e6SEdward Tomasz Napieralafor 9231a13f2e6SEdward Tomasz Napierala.Fa buf 9241a13f2e6SEdward Tomasz Napieralais returned. 9251a13f2e6SEdward Tomasz Napierala.Pp 9261a13f2e6SEdward Tomasz Napierala.Fn stats_voistat_fetch_dptr 9271a13f2e6SEdward Tomasz Napieralareturns 0 on success, or EINVAL if any problems are detected with the arguments. 9281a13f2e6SEdward Tomasz Napierala.Pp 9291a13f2e6SEdward Tomasz Napierala.Fn stats_voistat_fetch_<dtype> 9301a13f2e6SEdward Tomasz Napieralareturns 0 on success, or an errno on failure. 9311a13f2e6SEdward Tomasz NapieralaEINVAL is returned if any problems are detected with the arguments. 9321a13f2e6SEdward Tomasz NapieralaEFTYPE is returned if the requested data type does not match the blob's data 9331a13f2e6SEdward Tomasz Napieralatype for the specified 9341a13f2e6SEdward Tomasz Napierala.Fa voi_id 9351a13f2e6SEdward Tomasz Napieralaand 9361a13f2e6SEdward Tomasz Napierala.Fa stype . 9371a13f2e6SEdward Tomasz Napierala.Sh SEE ALSO 9381a13f2e6SEdward Tomasz Napierala.Xr errno 2 , 9391a13f2e6SEdward Tomasz Napierala.Xr arb 3 , 9401a13f2e6SEdward Tomasz Napierala.Xr qmath 3 , 9411a13f2e6SEdward Tomasz Napierala.Xr tcp 4 , 9421a13f2e6SEdward Tomasz Napierala.Xr sbuf 9 9431a13f2e6SEdward Tomasz Napierala.Rs 9441a13f2e6SEdward Tomasz Napierala.%A "Ted Dunning" 9451a13f2e6SEdward Tomasz Napierala.%A "Otmar Ertl" 9461a13f2e6SEdward Tomasz Napierala.%T "Computing Extremely Accurate Quantiles Using t-digests" 9471a13f2e6SEdward Tomasz Napierala.%U "https://github.com/tdunning/t-digest/raw/master/docs/t-digest-paper/histo.pdf" 9481a13f2e6SEdward Tomasz Napierala.Re 9491a13f2e6SEdward Tomasz Napierala.Sh HISTORY 9501a13f2e6SEdward Tomasz NapieralaThe 9511a13f2e6SEdward Tomasz Napierala.Nm 9521a13f2e6SEdward Tomasz Napieralaframework first appeared in 9531a13f2e6SEdward Tomasz Napierala.Fx 13.0 . 9541a13f2e6SEdward Tomasz Napierala.Sh AUTHORS 9551a13f2e6SEdward Tomasz Napierala.An -nosplit 9561a13f2e6SEdward Tomasz NapieralaThe 9571a13f2e6SEdward Tomasz Napierala.Nm 9581a13f2e6SEdward Tomasz Napieralaframework and this manual page were written by 9591a13f2e6SEdward Tomasz Napierala.An Lawrence Stewart Aq lstewart@FreeBSD.org 9601a13f2e6SEdward Tomasz Napieralaand sponsored by Netflix, Inc. 961359d7273SEdward Tomasz Napierala.Sh CAVEATS 962359d7273SEdward Tomasz NapieralaGranularity of timing-dependent network statistics, in particular TCP_RTT, 963359d7273SEdward Tomasz Napieraladepends on the 964359d7273SEdward Tomasz Napierala.Dv HZ 965359d7273SEdward Tomasz Napieralatimer. 966359d7273SEdward Tomasz NapieralaTo minimize the measurement error avoid using HZ lower than 1000. 967