From bc988244d4e3d07edd7f5ba0668744020c27f95b Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 19 Oct 2024 14:21:14 -0700 Subject: docs: statistics as a single chapter. --- docs/ref/api/stat/index.md | 23 --------- docs/ref/api/stat/nng_stat.md | 110 ----------------------------------------- docs/ref/api/stat/nng_stats.md | 107 --------------------------------------- 3 files changed, 240 deletions(-) delete mode 100644 docs/ref/api/stat/index.md delete mode 100644 docs/ref/api/stat/nng_stat.md delete mode 100644 docs/ref/api/stat/nng_stats.md (limited to 'docs/ref/api/stat') diff --git a/docs/ref/api/stat/index.md b/docs/ref/api/stat/index.md deleted file mode 100644 index 9bdceb55..00000000 --- a/docs/ref/api/stat/index.md +++ /dev/null @@ -1,23 +0,0 @@ -# Statistics - -To facilitate debugging and support situations, the _NNG_ library -supports collection and reporting of numerous statistics. - -These statistics are organized in a tree, and include both values, -and metadata describing the statistics. In order to be efficient and -minimize the impact of maintaining statistics, an explicit snapshot -of statistics must be taken, and that snapshot can then be processed. - -The following documentation will be useful: - -- [nng_stat](./nng_stat.md) - Single statistic -- [nng_stats](./nng_stats.md) - Statistics snapshot - -> [!NOTE] -> The presence, name, and semantics of any given statistic are -> subject to change at any time and without notice. -> Programmatic use is therefore discouraged. - -> [!NOTE] -> Statistics may be disabled by build-time configuration options, -> in order to reduce program size and run-time overheads. diff --git a/docs/ref/api/stat/nng_stat.md b/docs/ref/api/stat/nng_stat.md deleted file mode 100644 index a0d027af..00000000 --- a/docs/ref/api/stat/nng_stat.md +++ /dev/null @@ -1,110 +0,0 @@ -# nng_stat - -## NAME - -nng_stat --- statistic - -## SYNOPSIS - -```c -#include - -typedef struct nng_stat nng_stat; - -enum { - NNG_STAT_SCOPE, - NNG_STAT_LEVEL, - NNG_STAT_COUNTER, - NNG_STAT_STRING, - NNG_STAT_BOOLEAN, - NNG_STAT_ID -}; - -enum { - NNG_UNIT_NONE, - NNG_UNIT_BYTES, - NNG_UNIT_MESSAGES, - NNG_UNIT_MILLIS, - NNG_UNIT_EVENTS -}; - -int nng_stat_unit(nng_stat *stat); - -const char *nng_stat_name(nng_stat *stat); -const char *nng_stat_desc(nng_stat *stat); -int nng_stat_type(nng_stat *stat); -int nng_stat_unit(nng_stat *stat); -uint64_t nng_stat_value(nng_stat *stat); -const char *nng_stat_string(nng_stat *stat); -bool nng_stat_bool(nng_stat *stat); -uint64_t nng_stat_timestamp(nng_stat *stat); -``` - -## DESCRIPTION - -An {{i:`nng_stat`}} represents a {{i:statistic}}. -All statistics have names (retrievable with {{i:`nng_stat_name`}}) and -descriptions (retrievable with {{i:`nng_stat_desc`}}), and a -type (retrievable with {{i:`nng_stat_type`}}). - -Statistics also have a timestamp indicating when the value was sampled, -obtained via {{i:`nng_stat_timestamp`}}. The timestamp is given in -in milliseconds since a reference time, and the reference time used -here is the same reference time used for [`nng_clock`][nng_clock]. - -> [!NOTE] -> The presence, name, and semantics of any given statistic are -> subject to change at any time and without notice. - -### Statistic Values - -The type of a statistic determines the nature of the value, and which -function can be used to obtain that value. - -- {{i:`NNG_STAT_SCOPE`}}: The statistic does not carry any real value, but is - used for grouping related statistics together. This is a nexus in the - statistics tree. - -- {{i:`NNG_STAT_COUNTER`}}: The statistic is a counter that only increments. - Usually the change in the value of the statistic is more interesting - (as a rate) than the absolute value at any given time. The value should - be obtained using `nng_stat_value`. The units will be given by the value - returned from `nng_stat_unit`. - -- {{i:`NNG_STAT_LEVEL`}}: The statistic represnts a measured value which corresponds - to a specific value at a specific time. For example, this may represent the - number of messages currently queued for some operation, or the link speed - of a network interface. Most often the absolute value is more interesting - than the change in the value over time. Again the value can be obtained with - `nng_stat_value`, and any appropriate unit of measurement with `nng_stat_unit`. - -- {{i:`NNG_STAT_STRING`}}: The statistic is a string, such as a human. The value - of the string can be obtained with `nng_stat_string`. The value of this string - will remain valid until the snapshot is deallocated with [`nng_stats_free`][nng_stats]. - -- {{i:`NNG_STAT_BOOLEAN`}}: The value of the statistic is a truth value (either `true` - or `false`) and can be obtained with `nng_stat_bool`. - -- {{i:`NNG_STAT_ID`}}: The value of the statistic is a numeric identifier, such as a socket - identifier. The value can be obtained with `nng_stat_value`, and will generally not - change over time for a given statistic. - -### Statistic Units - -For statistics of type `NNG_STAT_COUNTER` or `NNG_STAT_LEVEL`, it is often -useful to know what that quantity being reported actually measures. -The following units may be returned from `nng_stat_unit` for such a statistic: - -- `NNG_UNIT_NONE`: No unit is known or applies. -- `NNG_UNIT_BYTES`: A count of bytes. -- `NNG_UNIT_MESSAGES`: A count of messages. -- `NNG_UNIT_MILLIS`: A count of milliseconds. -- `NNG_UNIT_EVENTS`: A count of events of some type. - -## SEE ALSO - -[nng_clock][nng_clock], -[nng_stats][nng_stats], - -[nng_clock]: ../util/nng_clock.md -[nng_stats]: ./nng_stats.md diff --git a/docs/ref/api/stat/nng_stats.md b/docs/ref/api/stat/nng_stats.md deleted file mode 100644 index a932ca5d..00000000 --- a/docs/ref/api/stat/nng_stats.md +++ /dev/null @@ -1,107 +0,0 @@ -# nng_stats - -## NAME - -nng_stats --- statistics snapshot - -## SYNOPSIS - -```c -#include - -typedef struct nng_stat nng_stat; - -int nng_stats_get(nng_stat **statsp); -void nng_stats_free(nng_stat *stats); -nng_stat *nng_stat_next(nng_stat *stat); -nng_stat *nng_stat_find(nng_stat *stat, const char *name); -nng_stat *nng_stat_find_dialer(nng_stat *stat, nng_dialer dialer); -nng_stat *nng_stat_find_listener(nng_stat *stat, nng_dialer listener); -nng_stat *nng_stat_find_socket(nng_stat *stat, nng_dialer socket); -``` - -## DESCRIPTION - -Statistics maintained by the system are organized in a tree, and -a snapshot of all statistics can be taken, and then traversed -and searched. - -### Statistics Snapshot Collection - -The {{i:`nng_stats_get`}} function attempts to obtain a snapshot of all the -various diagnostic statistics that are present in the system. -On success, a pointer to the statistics tree snapshot is returned in _statsp_. - -> [!NOTE] -> The process of collecting statistics is designed to have minimal -> impact on the system, but there is still some impact. - -The statistics are organized as a tree, rooted with a parent -statistic of type `NNG_STAT_SCOPE` that carries no value, and which -has an empty name. -This parent statistic is returned through the _statsp_ pointer. - -When no longer needed, the statistics snapshot can be freed with the -{{i:`nng_stats_free`}} function. - -> [!IMPORTANT] -> The `nng_stats_free` function must be called only with the root statistic that is -> returned through the _statsp_ pointer. - -> [!NOTE] -> The values of individual statistics are guaranteed to be atomic, -> but due the way statistics are collected there can be discrepancies between -> them at certain times. -> For example, statistics counting bytes and messages received may not -> reflect the same number of messages, depending on when the snapshot is taken. -> This potential inconsistency arises as a result of optimizations to minimize -> the impact of statistics on actual operations. - -### Traversing the Statistics Tree - -Traversing the tree of statistics is done using the `nng_stat_child` and -`nng_stat_next` functions. - -The `nng_stat_child` function returns either the first child of _stat_, -or `NULL` if the _stat_ has no children. - -The `nng_stat_next` function returns the nearest sibling to the right of _stat_, -or `NULL` if _stat_ has no more siblings to the right. - -### Finding a Statistic - -Sometimes it is easiest to search for a specific statistic, matching by name, -or possibly to find the tree of statistics associated iwth a specific [socket][nng_socket], -[dialer][nng_dialer], or [listener][nng_listener]. - -The `nng_stat_find` functions are provided for this purpose. - -The `nng_stat_find` function returns the first statistic within the subtree of -statistics _stat_, with the given _name_. If no such statistic can be found, `NULL` -is returned. - -The `nng_stat_find_dialer`, `nng_stat_find_listener`, and `nng_stat_find_socket` return -the statistics subtree for the given dialer, listener, or socket object. Note that -these functions should be provided the root of the statistic tree, in order to ensure -that they can find the desired object. - -## RETURN VALUES - -The `nng_stats_get` function returns zero on success, or a non-zero error value on failure. - -Aside from `nng_stats_free`, which has no return, the remaining functions return a pointer to -the desired statistic object, or `NULL` if such a statistic cannot be found. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient free memory to collect statistics. -- `NNG_ENOTSUP`: Statistics are not supported (compile time option). - -## SEE ALSO - -[nng_stat][nng_stat] - -[nng_stat]: ./nng_stat.md -[nng_socket]: TODO.md -[nng_dialer]: TODO.md -[nng_listener]: TODO.md -- cgit v1.2.3-70-g09d2