日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.4-RELEASE-K, 13.0-RELEASE-K から 13.3-RELEASE-K, 14.0-RELEASE-K から 14.1-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
STATS(3) FreeBSD ライブラリ関数マニュアル STATS(3)
名称
stats -- 集められる統計
ライブラリ
libstats Library (libstats -lstats)
書式
#include <sys/arb.h>
#include <sys/qmath.h>
#include <sys/stats.h>
Stats Blob Template Management Functions
int
stats_tpl_alloc(const char *name, uint32_t flags);
int
stats_tpl_fetch_allocid(const char *name, uint32_t hash);
int
stats_tpl_fetch(int tpl_id, struct statsblob_tpl **tpl);
int
stats_tpl_id2name(uint32_t tpl_id, char *buf, size_t len);
int
stats_tpl_sample_rates(SYSCTL_HANDLER_ARGS);
int
stats_tpl_sample_rollthedice(struct stats_tpl_sample_rate *rates,
int nrates, void *seed_bytes, size_t seed_len);
struct voistatspec
STATS_VSS_SUM();
struct voistatspec
STATS_VSS_MAX();
struct voistatspec
STATS_VSS_MIN();
struct voistatspec
STATS_VSS_CRHIST<32|64>_LIN(lb, ub, stepinc, vsdflags);
struct voistatspec
STATS_VSS_CRHIST<32|64>_EXP(lb, ub, stepbase, stepexp, vsdflags);
struct voistatspec
STATS_VSS_CRHIST<32|64>_LINEXP(lb, ub, nlinsteps, stepbase, vsdflags);
struct voistatspec
STATS_VSS_CRHIST<32|64>_USR(Sy,HBKTS,Ns,Pq,Sy,CRBKT,Ns,(,Em,lb,),
,,...,Pc, ,, vsdflags);
struct voistatspec
STATS_VSS_DRHIST<32|64>_USR(Sy,HBKTS,Ns,Pq,Sy,DRBKT,Ns,(,Em,lb, ,,ub,),
,,...,Pc, ,, vsdflags);
struct voistatspec
STATS_VSS_DVHIST<32|64>_USR(Sy,HBKTS,Ns,Pq,Sy,DVBKT,Ns,(,Em,val,),
,,...,Pc, ,, vsdflags);
struct voistatspec
STATS_VSS_TDGSTCLUST<32|64>(nctroids, prec);
int
stats_tpl_add_voistats(uint32_t tpl_id, int32_t voi_id,
const char *voi_name, enum vsd_dtype voi_dtype, uint32_t nvss,
struct voistatspec *vss, uint32_t flags);
Stats Blob Data Gathering Functions
int
stats_voi_update_<abs|rel>_<dtype>(struct statsblob *sb, int32_t voi_id,
<dtype> voival);
Stats Blob Utility Functions
struct statsblob *
stats_blob_alloc(uint32_t tpl_id, uint32_t flags);
int
stats_blob_init(struct statsblob *sb, uint32_t tpl_id, uint32_t flags);
int
stats_blob_clone(struct statsblob **dst, size_t dstmaxsz,
struct statsblob *src, uint32_t flags);
void
stats_blob_destroy(struct statsblob *sb);
int
stats_voistat_fetch_dptr(struct statsblob *sb, int32_t voi_id,
enum voi_stype stype, enum vsd_dtype *retdtype,
struct voistatdata **retvsd, size_t *retvsdsz);
int
stats_voistat_fetch_<dtype>(struct statsblob *sb, int32_t voi_id,
enum voi_stype stype, <dtype> *ret);
int
stats_blob_snapshot(struct statsblob **dst, size_t dstmaxsz,
struct statsblob *src, uint32_t flags);
int
stats_blob_tostr(struct statsblob *sb, struct sbuf *buf,
enum sb_str_fmt fmt, uint32_t flags);
int
stats_voistatdata_tostr(const struct voistatdata *vsd,
enum vsd_dtype dtype, enum sb_str_fmt fmt, struct sbuf *buf,
int objdump);
typedef int
(*stats_blob_visitcb_t)(struct sb_visit *sbv, void *usrctx);
int
stats_blob_visit(struct statsblob *sb, stats_blob_visitcb_t func,
void *usrctx);
解説
stats フレームワークは、実時間のカーネルと集められているユーザ空間の統計
を手助けします。フレームワークは、``statsblob''、消費者のためにほとんど不
透明である連続するメモリ割り付け内に埋め込まれたオブジェクトのまわりで構
築され、すべての必要であった状態を格納します。``statsblob'' オブジェクト
は、ポインタを直接、または間接的に使用する他のオブジェクト内にそれ自体を
埋め込むことができます。
統計が集められオブジェクトまたはサブシステムは、興味がある変数 (Variables
Of Interest; VOI) とそれらの関連する統計の任意の集合のための青写真として
動作する、テンプレート ``statsblob'' から初期化されます。各テンプレート
は、blob (ブロブ) のメモリフットプリントを最小化するために個別のままにさ
れる、スキーマと関連するメタデータを定義します。
フック関数を集めているデータは、興味あるフィード (feed) VOI データのコー
ドベース内の適切な位置で処理のためのフレームワークに追加します。
各 ``statsblob'' は、struct statsblob ヘッダと続くデータグラムごとに不透
明な内部の blob structure から成ります。
---------------------------------------------------------
| struct | uint8_t |
| statsblob | opaque[] |
---------------------------------------------------------
公的に可視である 8 バイトヘッダは、次のように定義されます:
struct statsblob {
uint8_t abi;
uint8_t endian;
uint16_t flags;
uint16_t maxsz;
uint16_t cursz;
uint8_t opaque[];
};
abi は、API バージョンの blob の opaque (不透明な) 内部が (STATS_ABI_V1
は、現在定義された唯一のバージョンである) ことに適合することを指定しま
す。endian は、blob のフィールド (リトルエンディアンのための SB_LE、ビッ
グエンディアンのための SB_BE、または未知のエンディアンの区別のための
SB_UE) のエンディアンの区別を指定します。cursz は、blob のサイズを指定し
ます、一方、maxsz は、blob が埋め込まれる基本的なメモリ割り付けのサイズを
指定します。cursz と maxsz の両方は、フラグが flags に設定されていないな
ら、バイトの単位をデフォルトとし、そうでなければ、指示します。
テンプレートは、各統計量が、以下の定義ごとに struct voistatspec を使用し
て指定される、統計の集合と任意の VOI ID を関連付けることによって構成され
ます。
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;
};
一般的に、消費者が struct voistatspec で直接動作しないことを期待され、
STATS_VSS_*() ヘルパマクロを使用する代りです。
stats フレームワークは、VOI と関連する次の統計を提供します:
VS_STYPE_SUM VOI 値の合計。
VS_STYPE_MAX 最大の VOI 値。
VS_STYPE_MIN 最小の VOI 値。
VS_STYPE_HIST VOI 値の静的なバケツヒストグラムは、``out-of
band/bucket'' の値のカウントを含んで、あらゆるバケツと一
致しません。VOI セマンティクスに依存して、32 または 64
ビットバケットカウンタがある、``Continuous Range''
(CRHIST), ``Discrete Range'' (DRHIST) または ``Discrete
Value'' (DVHIST), としてヒストグラムを指定することができ
ます。
VS_STYPE_TDGST VOI 値の動的なバケツヒストグラムは、t-digest 方法に基づい
ています (以下の「関連項目」セクションの t-digest 論文を
参照してください)。
``visitor software design pattern''(ビジタのソフトウェア設計パターン) に
似たスキームは、blob の構造のための懸念なしで blob のデータに渡って繰り返
すことを容易にするように採用されます。ビジタのコールバック関数に提供され
たデータは、以下の定義ごとに struct sb_visit でカプセル化されます:
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;
};
stats_tpl_sample_rates() と stats_tpl_sample_rollthedice() 関数は、以下の
定義ごとにテンプレートごとのサンプルレート情報をカプセル化するために、
struct stats_tpl_sample_rate を利用します:
struct stats_tpl_sample_rate {
int32_t tpl_slot_id;
uint32_t tpl_sample_pct;
};
tpl_slot_id メンバは、stats_tpl_alloc() または stats_tpl_fetch_allocid()
から取得されたテンプレートのスロット ID を保持します。tpl_sample_pct メン
バは、範囲 [0,100] の整数のパーセンテージとしてテンプレートのサンプルレー
トを保持します。
stats_tpl_sr_cb_t は、stats_tpl_sample_rates() の arg1 が次のように定義さ
れるように必要とされる関数ポインタに適合します:
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);
それは、適合している関数を必要とします:
- エラーで適切な errno(2) を返します、そうでなければ、0 を返します。
- "action == TPL_SR_*_GET" で呼び出されるとき、要求されるようにロックさ
れるか、または、アンロックされる、ptr とカウントをリストするサブシス
テムのレートを返します。
- "action == TPL_SR_RUNLOCK" で呼び出されるとき、ptr とカウントをリスト
するサブシステムのレートをアンロックします。事前の "action ==
TPL_SR_RLOCKED_GET" 呼び出しとペアになります。
- "action == TPL_SR_PUT" で呼び出されるとき、sysctl 処理された値に ptr
とカウントをリストするサブシステムのレート更新し、
stats_tpl_sample_rates() によって、ガベージコレクションのための rates
と nrates のアクティブでないリストの詳細を返します。
例えば、MIB 変数を通して、テンプレートがテキスト形式の意味を参照する必要
があるところで、次の文字列に基づいたテンプレートのスペック形式が、使用さ
れます:
1. "<tplname>":<tplhash> , 例えば "TCP_DEFAULT":1731235399
2. "<tplname>" , 例えば "TCP_DEFAULT"
3. :<tplhash> , 例えば :1731235399
最初の形式は、フレームワークによって生成された標準的なスペック形式です、
一方、2 番目と 3 番目の形式は、主にユーザ入力のために便利さ形式です。テン
プレート名のまわりの引用符の使用は、オプションです。
MIB 変数
カーネル内の stats フレームワークは、sysctl(3) MIB の kern.stats ブランチ
の次のフレームワーク特有な変数を公開します。
templates 標準的なテンプレートスペック形式の登録されたテンプレートの読み
込み専用 CSV リスト。
テンプレート管理関数
stats_tpl_alloc() 関数は、指定されたユニークな名前がある新しいテンプレー
トを割り付けて、他の API 関数で使用のための、その実行時の安定しているテン
プレートスロット ID を返します。flags 引数は、現在未使用です。
stats_tpl_fetch_allocid() 関数は、指定された名前とハッシュと一致している
あらゆる登録されたテンプレートの実行時に安定しているテンプレートスロット
ID を返します。
stats_tpl_fetch() 関数は、指定されたテンプレートスロット ID で、登録され
たテンプレートオブジェクトへのポインタを返します。
stats_tpl_id2name() 関数は、指定されたテンプレートスロット ID で、登録さ
れたテンプレートオブジェクトの名前を返します。
stats_tpl_sample_rates() 関数は、sysctl(3) MIB 変数を通してテンプレートサ
ンプルレート管理と報告のための一般的なハンドラを提供しています。サブシス
テムは、サブシステム特有のテンプレートのサンプリングレートを管理し、報告
するサブシステム特有の SYSCTL_PROC(9) MIB 変数を作成するために、この関数
を使用することができます。サブシステムは、サブシステムの状態テンプレート
サンプルレートリストと対話するために使用されるコールバックである、sysctl
の arg1 として stats_tpl_sr_cb_t 準拠関数のポインタを供給しなければなりま
せん。サブシステムは、arg2 サイズのコンテキストメモリの 0 で初期化された
割り付けが、ヒープ割り付けされる、0 以外として sysctl の arg2 をオプショ
ンで指定することができ、stats_tpl_sample_rates() の操作の間に行なわれたす
べてのサブシステムのコールバックに渡されます。
stats_tpl_sample_rollthedice() 関数は、テンプレートのサンプリングレートの
供給された配列から、重み付けられたランダムなテンプレート選択を行ないま
す。すべてのサンプリングレートの累積されるパーセンテージは、100 を越える
べきではありません。シード (種) が供給されないなら、PRNG は、すべての選択
が独立とできるように、真の乱数を生成するために使用されます。シード (種)
が供給されるなら、選択は、異なったシード (種) に渡ってランダムに行なわれ
ますが、確定的に同じシード (種) を与えます。
stats_tpl_add_voistats() 関数は、指定されたテンプレートスロット ID で、
VOI と関連した統計の集合を登録されたテンプレートオブジェクトに追加するた
めに使用されます。統計の集合は、STATS_VSS_*() ヘルパマクロまたは標準でな
い使用場合のための手動を使用して初期化することができる struct voistatspec
の配列として渡されます。静的な vss 配列のために、NVSS() マクロに vss を渡
すことによって、配列要素の nvss カウントを決定することができます。各更新
で blob の特別な 8 バイトの状態を保守することを必要とする、
stats_voi_update_rel_<dtype>() で使用のための VOI を設定するために、
SB_VOI_RELUPDATE フラグを渡すことができます。
データを集めている関数
stats_voi_update_abs_<dtype>() と stats_voi_update_rel_<dtype>() 関数の両
方は、voi_id によって識別される VOI に関連するすべての統計を更新します。
``abs'' 呼び出しは、絶対値として voival を使用するのに対して、``rel'' 呼
び出しは、前の値に追加することによって、更新のための結果を使用して、前の
更新関数呼び出しのものと関連する値として、voival を使用します。相対的な更
新は、stats_tpl_add_voistats() に指定された SB_VOI_RELUPDATE フラグでテン
プレートに追加された VOI のためにだけに可能です。
ユーティリティ関数
stats_blob_alloc() 関数は、指定されたテンプレートのスロット ID で、登録さ
れたテンプレートのオブジェクトに基づいて新しい blob を割り付けて、初期化
します。
stats_blob_init() 関数は、指定されたテンプレートのスロット ID で、登録さ
れたテンプレートのオブジェクトに基づいて既存のメモリ割り付けで新しい blob
を初期化します。
stats_blob_clone() 関数は、変更されない dst の maxsz フィールドのみそのま
まにして、dst に src blob を複製します。*dst に新しいポインタを格納して、
src をクローン化するものに適切なサイズの新しい blob を割り付けて、関数に
指示するために SB_CLONE_ALLOCDST フラグを渡すことができます。*dst がユー
ザ空間のアドレスであるので、copyout_nofault(9) または copyout(9) が使用さ
れるべきである、それぞれのシグナルに SB_CLONE_USRDSTNOFAULT または
SB_CLONE_USRDST フラグを設定することができます。
stats_blob_snapshot() 関数は、src のコピーを取得するために
stats_blob_clone() を呼び出し、次に、コヒーレントな blob スナップショット
を生成するために必要なあらゆる追加の関数を実行します。また、
stats_blob_clone() によって解釈されたフラグは、stats_blob_snapshot() に適
用します。さらに、スナップショットが成功して取られた後に、src の blob の
統計のリセットにもたらすように SB_CLONE_RSTSRC フラグを使用することができ
ます。
stats_blob_destroy() 関数は、以前に stats_blob_alloc(),
stats_blob_clone() または stats_blob_snapshot() で作成された blob を破壊
します。
stats_blob_visit() 関数によって、呼び出し側は、blob の内容を通して繰り返
すことができます。コールバック関数 func は、struct sb_visit とユーザコン
テキスト引数 usrctx をコールバック関数に渡して、blob のすべての VOI と統
計量のために呼び出されます。コールバック関数に渡された sbv は、繰ろ返しに
関する役に立つメタデータを提供するために、flags struct メンバに次のフラグ
の集合の 1 つ以上があります。SB_IT_FIRST_CB, SB_IT_LAST_CB,
SB_IT_FIRST_VOI, SB_IT_LAST_VOI, SB_IT_FIRST_VOISTAT, SB_IT_LAST_VOISTAT,
SB_IT_NULLVOI と SB_IT_NULLVOISTAT。コールバック関数から 0 でないの値を返
すことは、繰り返しを終了します。
stats_blob_tostr() は、blob の文字列表現を sbuf(9) buf に与えます。現在サ
ポートされた表現形式は、SB_STRFMT_FREEFORM と SB_STRFMT_JSON です。デバッ
グまたは文字列からバイナリ blob 再構成の目的についてのバージョン特有の不
透明な実装の詳細を表現するために SB_TOSTR_OBJDUMP フラグを渡すことができ
ます。対応するテンプレートを検索するために blob テンプレートハッシュを使
用してテンプレートメタデータを文字列表現に表現するために、SB_TOSTR_META
フラグを渡すことができます。
stats_voistatdata_tostr() は、個別の統計のデータの文字列表現を sbuf(9)
buf に表現します。stats_blob_tostr() 関数によってサポートされた同じ表現の
形式を、指定することができ、objdump ブール値は、SB_TOSTR_OBJDUMP フラグと
同じ意味があります。
stats_voistat_fetch_dptr() 関数は、VOI voi_id のための指定された stype 統
計データに内部の blob ポインタを返します。stats_voistat_fetch_<dtype>()
関数は、簡単なデータタイプのための抽出を実行する
stats_voistat_fetch_dptr() のまわりの便利なラッパです。
実装に関する注
次の注は、STATS_ABI_V1 形式の statsblobs に適用します。
空間時間の複雑さ
blob は、ヘッダに続いている 3 つの個別のメモリ領域としてレイアウトされま
す:
------------------------------------------------------
| struct | struct | struct | struct |
| statsblobv1 | voi [] | voistat [] | voistatdata [] |
------------------------------------------------------
blob は、配列インデックスとして voi_id と enum voi_stype を使用して VOI
と統計の blob の状態 (それぞれ、struct voi のための 8 バイトと struct
voistat のための 8 バイト) をスパース配列に格納します。これは、連続してい
る番号を付けられた VOI および/または統計量タイプを指定しない、テンプレー
トのための空のスロットごとの 8 バイトの消耗したメモリの費用で、blob のあ
らゆる voi/voistat ペアへの O(1) アクセスを許可します。統計のためのデータ
記憶域は、空でないスロットペアのためだけに割り付けられます。
具体的な例を提供するために、次の指定がある blob:
- 2 つの ID0; ID 0 と 2; その順序でテンプレートにで追加される
- VOI 0 は、データタイプ int64_t で、stats_voi_update_rel_<dtype>() を
使用して相対的な更新のためのサポートを有効にするために
SB_VOI_RELUPDATE で設定され、そしてそれに関連する VS_STYPE_MIN 統計が
あります。
- VOI 2 は、それに関連する VS_STYPE_SUM と VS_STYPE_MAX 統計があるデー
タタイプ uint32_t です。
次のメモリレイアウトがあります:
--------------------------------------
| 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
stats_blob_tostr(), SB_STRFMT_FREEFORM fmt と SB_TOSTR_OBJDUMP フラグを使
用する文字列形式に提供されるとき、提供された出力は、次の通りです:
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
注: 上記の提供された出力に存在している "\" は、80 のカラム内のマニュアル
ページを保持するために挿入されたマニュアルの行の改行を示し、実際の出力の
一部分ではありません。
ロック
stats フレームワークは、個別の blob レベルであらゆる並列保護を提供せず、
代わりに、テンプレートがない blob を参照する API 関数を呼び出すとき、消費
者が相互排除を保証していることを必要とします。
テンプレートのリストは、カーネル内の rwlock(9) とテンプレート管理と blob
初期化操作の間の同時並行性をサポートするユーザ空間の pthread(3) rw ロック
で保護されます。
戻り値
stats_tpl_alloc() は、成功すれば実行時の安定しているテンプレートスロット
IDを返し、失敗すれば負の errno を返します。なんらかの問題が引数で検出され
るなら、-EINVAL が返されます。既存のテンプレートが同じ名前で登録されるな
ら、-EEXIST が、返されます。必要なメモリ割り付けが失敗するなら、-ENOMEM
が、返されます。
stats_tpl_fetch_allocid() は、実行時の安定しているテンプレートスロット ID
を返し、失敗すれば、負の errno を返します。登録されたテンプレートが、指定
された名前および/またはハッシュと一致していないなら、-ESRCH が、返されま
す。
stats_tpl_fetch() は、成功すれば、0 を返し、無効の tpl_id が指定されるな
ら、ENOENT を返します。
stats_tpl_id2name() は、成功すれば、0 を返し、失敗すれば、errno を返しま
す。len によって指定された buf の長さがテンプレートの名前を保持するために
は短すぎるなら、EOVERFLOW が返されます。無効の tpl_id が指定されるなら、
ENOENT が、返されます。
stats_tpl_sample_rollthedice() は、rates から選択された有効なテンプレート
のスロット ID を返し、NULL の選択が行なわれて、このロールを状態収集がない
なら、-1 を返します。
stats_tpl_add_voistats() は、成功すれば、0 を返し、失敗すれば、errno を返
します。なんらかの問題が引数で検出されるなら、EINVAL が、返されます。結果
の blob が最大のサイズを越えていたなら、EFBIG が、返されます。より多くの
VOI 状態を、以前に設定された VOI に追加する試みが行なわれるなら、EOPNOT
SUPP が、返されます。必要なメモリ割り付けが失敗するなら、ENOMEM が、返さ
れます。
stats_voi_update_abs_<dtype>() と stats_voi_update_rel_<dtype>() は、成功
すれば、0 を返し、なんらかの問題が引数で検出されるなら、EINVAL をを返しま
す。
stats_blob_init() は、成功すれば、0 を返し、失敗すれば、errno を返しま
す。なんらかの問題が引数で検出されるなら、EINVAL が、返されます。テンプ
レートの blob の cursz が初期化されている blob の maxsz より大きいなら、
EOVERFLOW が、返されます。
stats_blob_alloc() は、スロット ID tpl_id で指定されたテンプレートに基づ
いて、新しく割り付けられた、初期化された blob へのポインタを返し、メモリ
割り付けが失敗したなら、NULL を返します。
stats_blob_clone() と stats_blob_snapshot() は、成功すれば、0 を返し、失
敗すれば、errno を返します。なんらかの問題が引数で検出されるなら、EINVAL
が、返されます。SB_CLONE_ALLOCDST フラグが指定され、dst のためのメモリ割
り付けが失敗するなら、ENOMEM が、返されます。src blob の cursz が dst
blob の maxsz より大きいなら、EOVERFLOW が、返されます。
stats_blob_visit() は、成功すれが、0 を返し、なんらかの問題が引数で検出さ
れるなら、EINVAL が、返されます。
stats_blob_tostr() と stats_voistatdata_tostr() は、成功すれば、0 を返
し、失敗すれば、errno を返します。なんらかの問題が引数で検出されるなら、
EINVAL が、返され、そうでなければ、buf のための sbuf_error() によって返さ
れたあらゆるエラーが、返されます。
stats_voistat_fetch_dptr() は、成功すれば、0 を返し、なんらかの問題が引数
で検出されるなら、EINVAL が、返されます。
stats_voistat_fetch_<dtype>() は、成功すれば、0 を返し、失敗すれば、errno
を返します。なんらかの問題が引数で検出されるなら、EINVAL が、返されます。
要求されたデータタイプが、指定された voi_id と stype のための blob のデー
タタイプと一致していないなら、EFTYPE が、返されます。
関連項目
errno(2), arb(3), qmath(3), tcp(4), sbuf(9)
Ted Dunning and Otmar Ertl, Computing Extremely Accurate Quantiles Using
t-digests, https://github.com/tdunning/t-digest/raw/master/docs/t-digest
paper/histo.pdf.
歴史
stats フレームワークは、FreeBSD 13.0 ではじめて登場しました。
作者
stats フレームワークとこのマニュアルページは、Lawrence Stewart
<lstewart@FreeBSD.org> によって書かれ、Netflix, Inc. によって後援されまし
た。
警告
タイミング依存のネットワーク統計の粒度は、特定の TCP_RTT で、HZ タイマに
依存します。測定エラーを最小化するために、1000 より低い HZ を使用して回避
します。
FreeBSD 13.2 December 2, 2019 FreeBSD 13.2