From 4c83442e174b186f5ee22bc8744cc7cc2a890e13 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 15 Oct 2024 20:31:04 -0700 Subject: Stats API converted to mdbook. A number of small errors were fixed, and we tried to restructure this to be a bit more usable to readers. --- docs/man/libnng.3.adoc | 46 +++++++------- docs/man/nng_stat.5.adoc | 81 ------------------------ docs/man/nng_stat_bool.3.adoc | 50 --------------- docs/man/nng_stat_child.3.adoc | 51 --------------- docs/man/nng_stat_desc.3.adoc | 52 ---------------- docs/man/nng_stat_find.3.adoc | 51 --------------- docs/man/nng_stat_find_dialer.3.adoc | 55 ----------------- docs/man/nng_stat_find_listener.3.adoc | 55 ----------------- docs/man/nng_stat_find_socket.3.adoc | 55 ----------------- docs/man/nng_stat_name.3.adoc | 46 -------------- docs/man/nng_stat_next.3.adoc | 48 -------------- docs/man/nng_stat_string.3.adoc | 54 ---------------- docs/man/nng_stat_timestamp.3.adoc | 60 ------------------ docs/man/nng_stat_type.3.adoc | 95 ---------------------------- docs/man/nng_stat_unit.3.adoc | 86 -------------------------- docs/man/nng_stat_value.3.adoc | 50 --------------- docs/man/nng_stats_get.3.adoc | 86 -------------------------- docs/ref/SUMMARY.md | 5 ++ docs/ref/api/stat/index.md | 23 +++++++ docs/ref/api/stat/nng_stat.md | 110 +++++++++++++++++++++++++++++++++ docs/ref/api/stat/nng_stats.md | 107 ++++++++++++++++++++++++++++++++ 21 files changed, 268 insertions(+), 998 deletions(-) delete mode 100644 docs/man/nng_stat.5.adoc delete mode 100644 docs/man/nng_stat_bool.3.adoc delete mode 100644 docs/man/nng_stat_child.3.adoc delete mode 100644 docs/man/nng_stat_desc.3.adoc delete mode 100644 docs/man/nng_stat_find.3.adoc delete mode 100644 docs/man/nng_stat_find_dialer.3.adoc delete mode 100644 docs/man/nng_stat_find_listener.3.adoc delete mode 100644 docs/man/nng_stat_find_socket.3.adoc delete mode 100644 docs/man/nng_stat_name.3.adoc delete mode 100644 docs/man/nng_stat_next.3.adoc delete mode 100644 docs/man/nng_stat_string.3.adoc delete mode 100644 docs/man/nng_stat_timestamp.3.adoc delete mode 100644 docs/man/nng_stat_type.3.adoc delete mode 100644 docs/man/nng_stat_unit.3.adoc delete mode 100644 docs/man/nng_stat_value.3.adoc delete mode 100644 docs/man/nng_stats_get.3.adoc create mode 100644 docs/ref/api/stat/index.md create mode 100644 docs/ref/api/stat/nng_stat.md create mode 100644 docs/ref/api/stat/nng_stats.md (limited to 'docs') diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 4183c316..0df0990d 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -229,29 +229,29 @@ that route messages from one socket to another. |xref:nng_device.3.adoc[nng_device()]|message forwarding device |=== -=== Statistics +// === Statistics -The following functions provide access to statistics which can be used -to observe program behaviors and as an aid in troubleshooting. +// The following functions provide access to statistics which can be used +// to observe program behaviors and as an aid in troubleshooting. -|=== -|xref:nng_stat_bool.3.adoc[nng_stat_bool()]|get statistic Boolean value -|xref:nng_stat_child.3.adoc[nng_stat_child()]|get child statistic -|xref:nng_stat_desc.3.adoc[nng_stat_name()]|get statistic description -|xref:nng_stat_find.3.adoc[nng_stat_find()]|find statistic by name -|xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer()]|find dialer statistics -|xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener()]|find listener statistics -|xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket()]|find socket statistics -|xref:nng_stat_name.3.adoc[nng_stat_name()]|get statistic name -|xref:nng_stat_next.3.adoc[nng_stat_next()]|get next statistic -|xref:nng_stat_string.3.adoc[nng_stat_string()]|get statistic string value -|xref:nng_stat_timestamp.3.adoc[nng_stat_timestamp()]|get statistic timestamp -|xref:nng_stat_type.3.adoc[nng_stat_type()]|get statistic type -|xref:nng_stat_unit.3.adoc[nng_stat_unit()]|get statistic unit -|xref:nng_stat_value.3.adoc[nng_stat_value()]|get statistic numeric value -|xref:nng_stats_free.3.adoc[nng_stats_free()]|free statistics -|xref:nng_stats_get.3.adoc[nng_stats_get()]|get statistics -|=== +// |=== +// |xref:nng_stat_bool.3.adoc[nng_stat_bool()]|get statistic Boolean value +// |xref:nng_stat_child.3.adoc[nng_stat_child()]|get child statistic +// |xref:nng_stat_desc.3.adoc[nng_stat_name()]|get statistic description +// |xref:nng_stat_find.3.adoc[nng_stat_find()]|find statistic by name +// |xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer()]|find dialer statistics +// |xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener()]|find listener statistics +// |xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket()]|find socket statistics +// |xref:nng_stat_name.3.adoc[nng_stat_name()]|get statistic name +// |xref:nng_stat_next.3.adoc[nng_stat_next()]|get next statistic +// |xref:nng_stat_string.3.adoc[nng_stat_string()]|get statistic string value +// |xref:nng_stat_timestamp.3.adoc[nng_stat_timestamp()]|get statistic timestamp +// |xref:nng_stat_type.3.adoc[nng_stat_type()]|get statistic type +// |xref:nng_stat_unit.3.adoc[nng_stat_unit()]|get statistic unit +// |xref:nng_stat_value.3.adoc[nng_stat_value()]|get statistic numeric value +// |xref:nng_stats_free.3.adoc[nng_stats_free()]|free statistics +// |xref:nng_stats_get.3.adoc[nng_stats_get()]|get statistics +// |=== // === URL Object @@ -275,9 +275,9 @@ to observe program behaviors and as an aid in troubleshooting. // |xref:nng_log_logger.3.adoc[nng_log_set_logger()]|set logging handler // |=== -=== Supplemental API +// === Supplemental API -NOTE: All these functions have been moved to new mdbook docs. +// NOTE: All these functions have been moved to new mdbook docs. // These supplemental functions are not intrinsic to building // network applications with _NNG_, but they are made available diff --git a/docs/man/nng_stat.5.adoc b/docs/man/nng_stat.5.adoc deleted file mode 100644 index 218bafb2..00000000 --- a/docs/man/nng_stat.5.adoc +++ /dev/null @@ -1,81 +0,0 @@ -= nng_stat(5) - -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. - -== NAME - -nng_stat - statistic - -== SYNOPSIS - -[source, c] ----- -#include - -typedef struct nng_stat nng_stat; ----- - -== DESCRIPTION - -An `nng_stat`(((statistic))) represents a statistic. -All statistics have names (xref:nng_stat_name.3.adoc[`nng_stat_name()`]) and -descriptions (xref:nng_stat_desc.3.adoc[`nng_stat_desc()`]), and are -typed (xref:nng_stat_type.3.adoc[`nng_stat_type()`]). - -Most statistics are numeric, -and thus carry a value (xref:nng_stat_value.3.adoc[`nng_stat_value()`]) -and frequently also a unit that the value measures (xref:nng_stat_unit.3.adoc[`nng_stat_unit()`]). - -Some statistics however, are simply strings (xref:nng_stat_string.3.adoc[`nng_stat_string()`]), -and thus carry no numeric value. - -Statistics are organized as a tree, and any given statistic can have siblings -(xref:nng_stat_next.3.adoc[`nng_stat_next()`]). -Note however that generally only `NNG_STAT_SCOPE` statistics, which are -act as placeholders in the tree (and carry no value), -will have children (xref:nng_stat_child.3.adoc[`nng_stat_child()`]). - -A tree of statistics is collected using xref:nng_stats_get.3.adoc[`nng_stats_get()`], -and can be freed when no longer needed with xref:nng_stats_free.3.adoc[`nng_stats_free()`]. -This collection process is generally performed in a way to minimize impact -to running operations, but there is still some impact caused by collection -of statistics. - -The time when a statistic's value is captured can be obtained using -xref:nng_stat_timestamp.3.adoc[`nng_stat_timestamp()`], which is useful for -measuring rates of change in certain statistics. - -NOTE: The presence, names, and meanings of any given statistic are -subject to change at any time. These statistics are provided as an aid -for debugging, and should generally not be relied upon for programmatic -behaviors. - -NOTE: Statistics may be disabled by build-time configuration options, -in order to reduce program size and run-time overheads. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_stats_free.3.adoc[nng_stats_free(3)], -xref:nng_stats_get.3.adoc[nng_stats_get(3)], -xref:nng_stat_child.3.adoc[nng_stat_child(3)], -xref:nng_stat_desc.3.adoc[nng_stat_desc(3)], -xref:nng_stat_find.3.adoc[nng_stat_find(3)], -xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer(3)], -xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener(3)], -xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket(3)], -xref:nng_stat_name.3.adoc[nng_stat_name(3)], -xref:nng_stat_next.3.adoc[nng_stat_next(3)], -xref:nng_stat_string.3.adoc[nng_stat_string(3)], -xref:nng_stat_timestamp.3.adoc[nng_stat_timestamp(3)], -xref:nng_stat_type.3.adoc[nng_stat_type(3)], -xref:nng_stat_unit.3.adoc[nng_stat_unit(3)], -xref:nng_stat_value.3.adoc[nng_stat_value(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stat_bool.3.adoc b/docs/man/nng_stat_bool.3.adoc deleted file mode 100644 index 678b45aa..00000000 --- a/docs/man/nng_stat_bool.3.adoc +++ /dev/null @@ -1,50 +0,0 @@ -= nng_stat_bool(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stat_bool - get statistic Boolean value - -== SYNOPSIS - -[source, c] ----- -#include - -typedef struct nng_stat nng_stat; - -bool nng_stat_bool(nng_stat *stat); ----- - -== DESCRIPTION - -The `nng_stat_bool()` function returns the Boolean value for the statistic _stat_. -Otherwise, if the statistic is not of Boolean type, the result is indeterminate. -See xref:nng_stat_type.3.adoc[`nng_stat_type()`] for a description of statistic types. - -== RETURN VALUES - -The boolean value associated with _stat_. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_stats_get.3.adoc[nng_stats_get(3)], -xref:nng_stat_type.3.adoc[nng_stat_type(3)], -xref:nng_stat_unit.3.adoc[nng_stat_unit(3)], -xref:nng_stat_value.3.adoc[nng_stat_value(3)], -xref:nng_stat.5.adoc[nng_stat(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stat_child.3.adoc b/docs/man/nng_stat_child.3.adoc deleted file mode 100644 index 123ca82d..00000000 --- a/docs/man/nng_stat_child.3.adoc +++ /dev/null @@ -1,51 +0,0 @@ -= nng_stat_child(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stat_child - get child statistic - -== SYNOPSIS - -[source, c] ----- -#include - -typedef struct nng_stat nng_stat; - -nng_stat *nng_stat_child(nng_stat *parent); ----- - -== DESCRIPTION - -The `nng_stat_child()` function returns the first child statistic of the -statistic _parent_. -If no children are present, then `NULL` is returned. - -TIP: Only statistics with type (see xref:nng_stat_type.3.adoc[`nng_stat_type()`]) -of `NNG_STAT_SCOPE` will have children. - -== RETURN VALUES - -The first child statistic of _parent_, or NULL if _parent_ has no children. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_stat_next.3.adoc[nng_stat_next(3)], -xref:nng_stats_get.3.adoc[nng_stats_get(3)], -xref:nng_stat.5.adoc[nng_stat(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stat_desc.3.adoc b/docs/man/nng_stat_desc.3.adoc deleted file mode 100644 index e87849d3..00000000 --- a/docs/man/nng_stat_desc.3.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_stat_desc(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stat_desc - get statistic description - -== SYNOPSIS - -[source, c] ----- -#include - -typedef struct nng_stat nng_stat; - -const char *nng_stat_desc(nng_stat *stat); ----- - -== DESCRIPTION - -The `nng_stat_desc()` function returns a brief, human-readable description -for the statistic _stat_. - -TIP: This description can be used for a tool-tip in user interfaces -displaying these statistic values. - -NOTE: At this time, only English descriptions are provided. - -== RETURN VALUES - -The description of statistic _stat_. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_stat_name.3.adoc[nng_stats_name(3)], -xref:nng_stats_get.3.adoc[nng_stats_get(3)], -xref:nng_stat.5.adoc[nng_stat(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stat_find.3.adoc b/docs/man/nng_stat_find.3.adoc deleted file mode 100644 index cdcf461f..00000000 --- a/docs/man/nng_stat_find.3.adoc +++ /dev/null @@ -1,51 +0,0 @@ -= nng_stat_find(3) - -// Copyright 2019 Staysail Systems, Inc. -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. - -== NAME - -nng_stat_find - find statistic by name - -== SYNOPSIS - -[source,c] ----- -#include - -typedef struct nng_stat nng_stat; - -nng_stat *nng_stat_find(nng_stat *stat, const char *name); ----- - -== DESCRIPTION - -The `nng_stat_find()` function searches the statistics tree _stat_, looking for a statistic whose name is _name_. -If it finds one, it returns it. -Otherwise `NULL` is returned. - -NOTE: If multiple statistics have that name, then only the first match is returned. - -== RETURN VALUES - -The matching statistic, or NULL if no match is found. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_stat_child.3.adoc[nng_stat_child(3)], -xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer(3)], -xref:nng_stat_find_listener.3.adoc[nng_stat_find_listner(3)], -xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket(3)], -xref:nng_stats_get.3.adoc[nng_stats_get(3)], -xref:nng_stat.5.adoc[nng_stat(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stat_find_dialer.3.adoc b/docs/man/nng_stat_find_dialer.3.adoc deleted file mode 100644 index 202fd289..00000000 --- a/docs/man/nng_stat_find_dialer.3.adoc +++ /dev/null @@ -1,55 +0,0 @@ -= nng_stat_find_dialer(3) - -// Copyright 2020 Staysail Systems, Inc. -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. - -== NAME - -nng_stat_find_dialer - find dialer statistics - -== SYNOPSIS - -[source,c] ----- -#include - -typedef struct nng_stat nng_stat; -typedef struct nng_dialer nng_dialer; - -nng_stat *nng_stat_find_dialer(nng_stat *stat, nng_dialer dialer); ----- - -== DESCRIPTION - -The `nng_stat_find_dialer()` function returns the statistics tree within _stat_ associated with the dialer _dialer_, if such a tree exists. -Otherwise `NULL` is returned. - -Generally, there will be child statistics of the returned value, each corresponding to a specific metric. -These can be further scanned using either -xref:nng_stat_find.3.adoc[nng_stat_find(3)] -or by walking the tree with -xref:nng_stat_child.3.adoc[nng_stat_child(3)]. - -== RETURN VALUES - -The matching statistic, or NULL if no match is found. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_stat_child.3.adoc[nng_stat_child(3)], -xref:nng_stat_find.3.adoc[nng_stat_find(3)], -xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener(3)], -xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket(3)], -xref:nng_stats_get.3.adoc[nng_stats_get(3)], -xref:nng_stat.5.adoc[nng_stat(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stat_find_listener.3.adoc b/docs/man/nng_stat_find_listener.3.adoc deleted file mode 100644 index 46c2dc74..00000000 --- a/docs/man/nng_stat_find_listener.3.adoc +++ /dev/null @@ -1,55 +0,0 @@ -= nng_stat_find_listener(3) - -// Copyright 2019 Staysail Systems, Inc. -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. - -== NAME - -nng_stat_find_listener - find listener statistics - -== SYNOPSIS - -[source,c] ----- -#include - -typedef struct nng_stat nng_stat; -typedef struct nng_listener nng_listener; - -nng_stat *nng_stat_find_listener(nng_stat *stat, nng_listener listener); ----- - -== DESCRIPTION - -The `nng_stat_find_listener()` function returns the statistics tree within _stat_ associated with the listener _listener_, if such a tree exists. -Otherwise `NULL` is returned. - -Generally, there will be child statistics of the returned value, each corresponding to a specific metric. -These can be further scanned using either -xref:nng_stat_find.3.adoc[nng_stat_find(3)] -or by walking the tree with -xref:nng_stat_child.3.adoc[nng_stat_child(3)]. - -== RETURN VALUES - -The matching statistic, or NULL if no match is found. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_stat_child.3.adoc[nng_stat_child(3)], -xref:nng_stat_find.3.adoc[nng_stat_find(3)], -xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer(3)], -xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket(3)], -xref:nng_stats_get.3.adoc[nng_stats_get(3)], -xref:nng_stat.5.adoc[nng_stat(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stat_find_socket.3.adoc b/docs/man/nng_stat_find_socket.3.adoc deleted file mode 100644 index deea509c..00000000 --- a/docs/man/nng_stat_find_socket.3.adoc +++ /dev/null @@ -1,55 +0,0 @@ -= nng_stat_find_socket(3) - -// Copyright 2019 Staysail Systems, Inc. -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. - -== NAME - -nng_stat_find_socket - find socket statistics - -== SYNOPSIS - -[source,c] ----- -#include - -typedef struct nng_stat nng_stat; -typedef struct nng_socket nng_socket; - -nng_stat *nng_stat_find_socket(nng_stat *stat, nng_socket socket); ----- - -== DESCRIPTION - -The `nng_stat_find_socket()` function returns the statistics tree within _stat_ associated with the socket _socket_, if such a tree exists. -Otherwise `NULL` is returned. - -Generally, there will be child statistics of the returned value, each corresponding to a specific metric. -These can be further scanned using either -xref:nng_stat_find.3.adoc[nng_stat_find(3)] -or by walking the tree with -xref:nng_stat_child.3.adoc[nng_stat_child(3)]. - -== RETURN VALUES - -The matching statistic, or NULL if no match is found. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_stat_child.3.adoc[nng_stat_child(3)], -xref:nng_stat_find.3.adoc[nng_stat_find(3)], -xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer(3)], -xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener(3)], -xref:nng_stats_get.3.adoc[nng_stats_get(3)], -xref:nng_stat.5.adoc[nng_stat(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stat_name.3.adoc b/docs/man/nng_stat_name.3.adoc deleted file mode 100644 index bf2fd3c7..00000000 --- a/docs/man/nng_stat_name.3.adoc +++ /dev/null @@ -1,46 +0,0 @@ -= nng_stat_name(3) - -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. - -== NAME - -nng_stat_name - get statistic name - -== SYNOPSIS - -[source, c] ----- -#include - -typedef struct nng_stat nng_stat; - -const char *nng_stat_name(nng_stat *stat); ----- - -== DESCRIPTION - -The `nng_stat_name()` function returns the name for the statistic _stat_. - -NOTE: The global root statistic will have the empty string ("") as it's name. - -== RETURN VALUES - -The name of statistic _stat_. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_stats_get.3.adoc[nng_stats_get(3)], -xref:nng_stat.5.adoc[nng_stat(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stat_next.3.adoc b/docs/man/nng_stat_next.3.adoc deleted file mode 100644 index 00caa5c8..00000000 --- a/docs/man/nng_stat_next.3.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= nng_stat_next(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stat_next - get next statistic - -== SYNOPSIS - -[source, c] ----- -#include - -typedef struct nng_stat nng_stat; - -nng_stat *nng_stat_next(nng_stat *stat); ----- - -== DESCRIPTION - -The `nng_stat_next()` function returns the next sibling statistic of the -statistic _stat_. -If no more siblings are present, then `NULL` is returned. - -== RETURN VALUES - -The next sibling statistic of _stat_, or NULL if _stat_ is the last sibling. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_stat_child.3.adoc[nng_stat_child(3)], -xref:nng_stats_get.3.adoc[nng_stats_get(3)], -xref:nng_stat.5.adoc[nng_stat(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stat_string.3.adoc b/docs/man/nng_stat_string.3.adoc deleted file mode 100644 index 4c65fb1a..00000000 --- a/docs/man/nng_stat_string.3.adoc +++ /dev/null @@ -1,54 +0,0 @@ -= nng_stat_string(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stat_string - get statistic string value - -== SYNOPSIS - -[source, c] ----- -#include - -typedef struct nng_stat nng_stat; - -const char *nng_stat_string(nng_stat *stat); ----- - -== DESCRIPTION - -The `nng_stat_string()` function returns a string value for the statistic _stat_, -which must be of type `NNG_STAT_STRING` (see xref:nng_stat_type.3.adoc[`nng_stat_type(3)`]). - -If the statistic is not of type `NNG_STAT_STRING`, then `NULL` will be returned. - -NOTE: The returned string is valid until xref:nng_stats_free.3.adoc[`nng_stats_free()`] is called to -free the memory for the snapshot. - -== RETURN VALUES - -The string value associated with _stat_, or `NULL` if the statistic is not -a string type. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_stats_get.3.adoc[nng_stats_get(3)], -xref:nng_stat_type.3.adoc[nng_stats_type(3)], -xref:nng_stat_value.3.adoc[nng_stats_value(3)], -xref:nng_stat.5.adoc[nng_stat(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stat_timestamp.3.adoc b/docs/man/nng_stat_timestamp.3.adoc deleted file mode 100644 index 74d827e8..00000000 --- a/docs/man/nng_stat_timestamp.3.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_stat_timestamp(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stat_timestamp - get statistic timestamp - -== SYNOPSIS - -[source, c] ----- -#include - -typedef struct nng_stat nng_stat; - -uint64_t nng_stat_timestamp(nng_stat *stat); ----- - -== DESCRIPTION - -The `nng_stat_timestamp()` function returns the a timestamp, which is measured -as a number of milliseconds since some arbitrary value in the past. - -Even within the same snapshot, statistics might have different timestamp -values, as the timestamp represents the time when that particular statistic -was captured. - -TIP: These values are intended to facilitate calculation of rates, by -comparing values from one snapshot with a subsequent one. - -TIP: The values used here have the same offset as the -xref:nng_clock.3supp.adoc[`nng_clock()`] supplemental function. -This can be useful when converting these values to local clock time. - -== RETURN VALUES - -The timestamp when _stat_ was captured, measured as a number of -milliseconds since some time in the past. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_stats_get.3.adoc[nng_stats_get(3)], -xref:nng_stat_value.3.adoc[nng_stat_value(3)], -xref:nng_clock.3supp.adoc[nng_clock(3supp)], -xref:nng_stat.5.adoc[nng_stat(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stat_type.3.adoc b/docs/man/nng_stat_type.3.adoc deleted file mode 100644 index a2578e5e..00000000 --- a/docs/man/nng_stat_type.3.adoc +++ /dev/null @@ -1,95 +0,0 @@ -= nng_stat_type(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stat_type - get statistic type - -== SYNOPSIS - -[source, 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 -}; - -int nng_stat_type(nng_stat *stat); ----- - -== DESCRIPTION - -The `nng_stat_type()` function returns the type of the statistic _stat_. - -The returned type will be one of the following values: - -((`NNG_STAT_SCOPE`)):: -This is a placeholder providing scope, and carries no value on its own. -Instead it is a parent node with child statistics (see -xref:nng_stat_child.3.adoc[`nng_stat_child()`].) - -((`NNG_STAT_LEVEL`)):: -This is a numeric statistic, but its value is a level, so rate calculations -based on changes in this value should not be considered significant. - -((`NNG_STAT_COUNTER`)):: -This is a numeric statistic that represents an increasing count, typically -of events, messages, or bytes. -Frequently, it is interesting to consider changes in this statistic divided -by time to obtain a rate. -(For example, throughput might be calculated as changes in a byte counter -divided by the interval over which the change occurred.) - -((`NNG_STAT_STRING`)):: -This is a string, and carries no numeric value. -Instead the xref:nng_stat_string.3.adoc[`nng_stat_string()`] function -should be used to obtain the value. - -((`NNG_STAT_BOOLEAN`)):: -This is a boolean value. -The xref:nng_stat_value.3.adoc[`nng_stat_value()`] function will return zero -to represent a `false` value, and one to represent a `true` value. - -((`NNG_STAT_ID`)): -The statistic is a numeric ID. -These are generally immutable values that represent an identity that might -be used with another interface. - -TIP: For `NNG_STAT_COUNTER` and `NNG_STAT_LEVEL` statistics, the -xref:nng_stat_unit.3.adoc[`nng_stat_unit()`] function will provide more -detail about the units measured by the static. - -== RETURN VALUES - -The statistic type for _stat_. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_stats_get.3.adoc[nng_stats_get(3)], -xref:nng_stat_string.3.adoc[nng_stat_string(3)], -xref:nng_stat_unit.3.adoc[nng_stat_unit(3)], -xref:nng_stat_value.3.adoc[nng_stat_value(3)], -xref:nng_stat.5.adoc[nng_stat(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stat_unit.3.adoc b/docs/man/nng_stat_unit.3.adoc deleted file mode 100644 index f7136e1f..00000000 --- a/docs/man/nng_stat_unit.3.adoc +++ /dev/null @@ -1,86 +0,0 @@ -= nng_stat_unit(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stat_unit - get statistic unit - -== SYNOPSIS - -[source, c] ----- -#include - -typedef struct nng_stat nng_stat; - -enum { - NNG_UNIT_NONE, - NNG_UNIT_BYTES, - NNG_UNIT_MESSAGES, - NNG_UNIT_MILLIS, - NNG_UNIT_EVENTS -}; - -int nng_stat_unit(nng_stat *stat); ----- - -== DESCRIPTION - -The `nng_stat_unit()` function returns the unit of quantity measured -by the statistic _stat_. - -The returned value will be one of the following values: - -((`NNG_UNIT_NONE`)):: -There are no particular units measured. -In some cases there may be units, but the type of the unit will be obvious -from the name (see xref:nng_stat_name.3.adoc[`nng_stat_name()`]) of the statistic. - -((`NNG_UNIT_BYTES`)):: -The statistic is a count of bytes. - -((`NNG_UNIT_MESSAGES`)):: -The statistic is a count of messages. -Typically, one message corresponds to a single xref:nng_msg.5.adoc[`nng_msg`] structure. - -((`NNG_UNIT_MILLIS`)):: -The statistic is a count of milliseconds. - -((`NNG_STAT_EVENTS`)):: -The statistic is a count of some other type of event. - -For statistics that are neither `NNG_STAT_COUNTER` nor `NNG_STAT_LEVEL` -type (see xref:nng_stat_type.3.adoc[`nng_stat_type()`]), the unit will -generally be `NNG_UNIT_NONE`. - -TIP: Normally rates can be calculated for `NNG_STAT_COUNTER` values for -any of these units, but for `NNG_UNIT_MILLIS` rate calculations are generally -meaningless. - -== RETURN VALUES - -The units measured by _stat_. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_stats_get.3.adoc[nng_stats_get(3)], -xref:nng_stat_name.3.adoc[nng_stat_name(3)], -xref:nng_stat_type.3.adoc[nng_stat_type(3)], -xref:nng_stat_value.3.adoc[nng_stat_value(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng_stat.5.adoc[nng_stat(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stat_value.3.adoc b/docs/man/nng_stat_value.3.adoc deleted file mode 100644 index d5d28473..00000000 --- a/docs/man/nng_stat_value.3.adoc +++ /dev/null @@ -1,50 +0,0 @@ -= nng_stat_value(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stat_value - get statistic numeric value - -== SYNOPSIS - -[source, c] ----- -#include - -typedef struct nng_stat nng_stat; - -uint64_t nng_stat_value(nng_stat *stat); ----- - -== DESCRIPTION - -The `nng_stat_value()` function returns a numeric value for the statistic _stat_. -If the statistic is not of numeric type, then zero is returned. -See xref:nng_stat_type.3.adoc[`nng_stat_type()`] for a description of statistic types. - -== RETURN VALUES - -The numeric value associated with _stat_. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng_stats_get.3.adoc[nng_stats_get(3)], -xref:nng_stat_bool.3.adoc[nng_stat_bool(3)], -xref:nng_stat_type.3.adoc[nng_stat_type(3)], -xref:nng_stat_unit.3.adoc[nng_stat_unit(3)], -xref:nng_stat.5.adoc[nng_stat(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_stats_get.3.adoc b/docs/man/nng_stats_get.3.adoc deleted file mode 100644 index 5cbb2624..00000000 --- a/docs/man/nng_stats_get.3.adoc +++ /dev/null @@ -1,86 +0,0 @@ -= nng_stats_get(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_stats_get - get statistics snapshot - -== SYNOPSIS - -[source, c] ----- -#include - -typedef struct nng_stat nng_stat; - -int nng_stats_get(nng_stat **statsp) ----- - -== DESCRIPTION - -The `nng_stat_get()` function attempts to obtain a snapshot of all the -various diagnostic statistics that are present in the system. - -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. - -The xref:nng_stat_child.3.adoc[`nng_stat_child()`] and -xref:nng_stat_next.3.adoc[`nng_stat_next()`] function can be used to -iterate over the the tree. - -When no longer needed, the statistics can be freed with the -xref:nng_stats_free.3.adoc[`nng_stats_free()`] function, but that -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. - -NOTE: The names, values, and semantics of statistics provided may change -from release to release. -These are provided for informational and debugging use only, and applications -should not rely on the presence, names, or meanings of any individual statistics. - -== RETURN VALUES - -This function returns a pointer to the allocated memory on success, -and `NULL` otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory to collect statistics. -`NNG_ENOTSUP`:: Statistics are not supported (compile time option). - -== SEE ALSO - -[.text-left] -xref:nng_stats_free.3.adoc[nng_stats_free(3)], -xref:nng_stat_child.3.adoc[nng_stat_child(3)], -xref:nng_stat_desc.3.adoc[nng_stat_desc(3)], -xref:nng_stat_name.3.adoc[nng_stat_name(3)], -xref:nng_stat_next.3.adoc[nng_stat_next(3)], -xref:nng_stat_string.3.adoc[nng_stat_string(3)], -xref:nng_stat_type.3.adoc[nng_stat_type(3)], -xref:nng_stat_timestamp.3.adoc[nng_stat_timestamp(3)], -xref:nng_stat_unit.3.adoc[nng_stat_unit(3)], -xref:nng_stat_value.3.adoc[nng_stat_value(3)], -xref:nng_stat.5.adoc[nng_stat(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 094eac11..b0dd9f51 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -26,6 +26,11 @@ - [nng_log_level](./api/log/nng_log_level.md) - [nng_log_logger](./api/log/nng_log_logger.md) + - [Statistics](./api/stat/index.md) + + - [nng_stat](./api/stat/nng_stat.md) + - [nng_stats](./api/stat/nng_stats.md) + - [Utility Functions](./api/util/index.md) - [nng_alloc](./api/util/nng_alloc.md) diff --git a/docs/ref/api/stat/index.md b/docs/ref/api/stat/index.md new file mode 100644 index 00000000..9bdceb55 --- /dev/null +++ b/docs/ref/api/stat/index.md @@ -0,0 +1,23 @@ +# 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 new file mode 100644 index 00000000..7010ac0b --- /dev/null +++ b/docs/ref/api/stat/nng_stat.md @@ -0,0 +1,110 @@ +# 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 new file mode 100644 index 00000000..a932ca5d --- /dev/null +++ b/docs/ref/api/stat/nng_stats.md @@ -0,0 +1,107 @@ +# 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