From c7f7bcb6e2cfbf66c7fab158b0ac02890243b5bb Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Mon, 8 Apr 2024 07:40:06 -0700 Subject: Converted stats pages --- docs/ref/stat/nng_stat_bool.adoc | 30 ++++++++++++++ docs/ref/stat/nng_stat_child.adoc | 29 ++++++++++++++ docs/ref/stat/nng_stat_desc.adoc | 30 ++++++++++++++ docs/ref/stat/nng_stat_find.adoc | 33 ++++++++++++++++ docs/ref/stat/nng_stat_find_dialer.adoc | 35 ++++++++++++++++ docs/ref/stat/nng_stat_find_listener.adoc | 38 ++++++++++++++++++ docs/ref/stat/nng_stat_find_socket.adoc | 35 ++++++++++++++++ docs/ref/stat/nng_stat_name.adoc | 27 +++++++++++++ docs/ref/stat/nng_stat_next.adoc | 28 +++++++++++++ docs/ref/stat/nng_stat_string.adoc | 31 +++++++++++++++ docs/ref/stat/nng_stat_timestamp.adoc | 34 ++++++++++++++++ docs/ref/stat/nng_stat_type.adoc | 66 +++++++++++++++++++++++++++++++ docs/ref/stat/nng_stat_unit.adoc | 59 +++++++++++++++++++++++++++ docs/ref/stat/nng_stat_value.adoc | 30 ++++++++++++++ 14 files changed, 505 insertions(+) create mode 100644 docs/ref/stat/nng_stat_bool.adoc create mode 100644 docs/ref/stat/nng_stat_child.adoc create mode 100644 docs/ref/stat/nng_stat_desc.adoc create mode 100644 docs/ref/stat/nng_stat_find.adoc create mode 100644 docs/ref/stat/nng_stat_find_dialer.adoc create mode 100644 docs/ref/stat/nng_stat_find_listener.adoc create mode 100644 docs/ref/stat/nng_stat_find_socket.adoc create mode 100644 docs/ref/stat/nng_stat_name.adoc create mode 100644 docs/ref/stat/nng_stat_next.adoc create mode 100644 docs/ref/stat/nng_stat_string.adoc create mode 100644 docs/ref/stat/nng_stat_timestamp.adoc create mode 100644 docs/ref/stat/nng_stat_type.adoc create mode 100644 docs/ref/stat/nng_stat_unit.adoc create mode 100644 docs/ref/stat/nng_stat_value.adoc (limited to 'docs/ref') diff --git a/docs/ref/stat/nng_stat_bool.adoc b/docs/ref/stat/nng_stat_bool.adoc new file mode 100644 index 00000000..9517464f --- /dev/null +++ b/docs/ref/stat/nng_stat_bool.adoc @@ -0,0 +1,30 @@ +## nng_stat_bool + +Get statistic Boolean value. + +### Synopsis + +```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.adoc[`nng_stat_type`] for a description of statistic types. + +### Return Values + +The boolean value associated with _stat_. + +### See Also + +xref:nng_stats_get.adoc[nng_stats_get], +xref:nng_stat_type.adoc[nng_stat_type], +xref:nng_stat_unit.adoc[nng_stat_unit], +xref:nng_stat_value.adoc[nng_stat_value] diff --git a/docs/ref/stat/nng_stat_child.adoc b/docs/ref/stat/nng_stat_child.adoc new file mode 100644 index 00000000..09bf98e1 --- /dev/null +++ b/docs/ref/stat/nng_stat_child.adoc @@ -0,0 +1,29 @@ +## nng_stat_child + +Get child statistic. + +### Synopsis + +```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.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. + +### See Also + +xref:nng_stat_next.adoc[nng_stat_next], +xref:nng_stats_get.adoc[nng_stats_get] diff --git a/docs/ref/stat/nng_stat_desc.adoc b/docs/ref/stat/nng_stat_desc.adoc new file mode 100644 index 00000000..b1079412 --- /dev/null +++ b/docs/ref/stat/nng_stat_desc.adoc @@ -0,0 +1,30 @@ +## nng_stat_desc + +Get statistic description. + +### Synopsis + +```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_. + +### See Also + +xref:nng_stat_name.adoc[nng_stats_name], +xref:nng_stats_get.adoc[nng_stats_get] diff --git a/docs/ref/stat/nng_stat_find.adoc b/docs/ref/stat/nng_stat_find.adoc new file mode 100644 index 00000000..2286475f --- /dev/null +++ b/docs/ref/stat/nng_stat_find.adoc @@ -0,0 +1,33 @@ +## nng_stat_find + +Find statistic by name. + +### Synopsis + +```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. + +### See Also + +xref:nng_stat_child.adoc[nng_stat_child], +xref:nng_stat_find_dialer.adoc[nng_stat_find_dialer], +xref:nng_stat_find_listener.adoc[nng_stat_find_listner], +xref:nng_stat_find_socket.adoc[nng_stat_find_socket], +xref:nng_stats_get.adoc[nng_stats_get] diff --git a/docs/ref/stat/nng_stat_find_dialer.adoc b/docs/ref/stat/nng_stat_find_dialer.adoc new file mode 100644 index 00000000..68195364 --- /dev/null +++ b/docs/ref/stat/nng_stat_find_dialer.adoc @@ -0,0 +1,35 @@ +## nng_stat_find_dialer + +Find dialer statistics. + +### Synopsis + +```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.adoc[nng_stat_find] +or by walking the tree with xref:nng_stat_child.adoc[nng_stat_child]. + +### Return Values + +The matching statistic, or NULL if no match is found. + +### See Also + +xref:nng_stat_child.adoc[nng_stat_child], +xref:nng_stat_find.adoc[nng_stat_find], +xref:nng_stat_find_listener.adoc[nng_stat_find_listener], +xref:nng_stat_find_socket.adoc[nng_stat_find_socket], +xref:nng_stats_get.adoc[nng_stats_get] diff --git a/docs/ref/stat/nng_stat_find_listener.adoc b/docs/ref/stat/nng_stat_find_listener.adoc new file mode 100644 index 00000000..81e5b037 --- /dev/null +++ b/docs/ref/stat/nng_stat_find_listener.adoc @@ -0,0 +1,38 @@ +## nng_stat_find_listener + +Find listener statistics. + +### Synopsis + +```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.adoc[nng_stat_find] or by walking the tree with xref:nng_stat_child.adoc[nng_stat_child]. + +### Return Values + +The matching statistic, or NULL if no match is found. + +### Errors + +None. + +### See Also + +xref:nng_stat_child.adoc[nng_stat_child], +xref:nng_stat_find.adoc[nng_stat_find], +xref:nng_stat_find_dialer.adoc[nng_stat_find_dialer], +xref:nng_stat_find_socket.adoc[nng_stat_find_socket], +xref:nng_stats_get.adoc[nng_stats_get] diff --git a/docs/ref/stat/nng_stat_find_socket.adoc b/docs/ref/stat/nng_stat_find_socket.adoc new file mode 100644 index 00000000..5cd61e36 --- /dev/null +++ b/docs/ref/stat/nng_stat_find_socket.adoc @@ -0,0 +1,35 @@ +## nng_stat_find_socket + +Find socket statistics. + +### Synopsis + +```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.adoc[nng_stat_find] or by walking the tree with +xref:nng_stat_child.adoc[nng_stat_child]. + +### Return Values + +The matching statistic, or NULL if no match is found. + +### See Also + +xref:nng_stat_child.adoc[nng_stat_child], +xref:nng_stat_find.adoc[nng_stat_find], +xref:nng_stat_find_dialer.adoc[nng_stat_find_dialer], +xref:nng_stat_find_listener.adoc[nng_stat_find_listener], +xref:nng_stats_get.adoc[nng_stats_get] diff --git a/docs/ref/stat/nng_stat_name.adoc b/docs/ref/stat/nng_stat_name.adoc new file mode 100644 index 00000000..ab9e2ace --- /dev/null +++ b/docs/ref/stat/nng_stat_name.adoc @@ -0,0 +1,27 @@ +## nng_stat_name + +Get statistic name. + +### Synopsis + +```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_. + +### See Also + +xref:nng_stats_get.adoc[nng_stats_get] diff --git a/docs/ref/stat/nng_stat_next.adoc b/docs/ref/stat/nng_stat_next.adoc new file mode 100644 index 00000000..09cc24f5 --- /dev/null +++ b/docs/ref/stat/nng_stat_next.adoc @@ -0,0 +1,28 @@ +## nng_stat_next + +Get next statistic. + +### Synopsis + +```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. + +### See Also + +xref:nng_stat_child.adoc[nng_stat_child], +xref:nng_stats_get.adoc[nng_stats_get] diff --git a/docs/ref/stat/nng_stat_string.adoc b/docs/ref/stat/nng_stat_string.adoc new file mode 100644 index 00000000..1933ced8 --- /dev/null +++ b/docs/ref/stat/nng_stat_string.adoc @@ -0,0 +1,31 @@ +## nng_stat_string + +Get statistic string value. + +### Synopsis + +```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.adoc[`nng_stat_type`]). + +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.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. + +### See Also + +xref:nng_stats_get.adoc[nng_stats_get], +xref:nng_stat_type.adoc[nng_stats_type], +xref:nng_stat_value.adoc[nng_stats_value] diff --git a/docs/ref/stat/nng_stat_timestamp.adoc b/docs/ref/stat/nng_stat_timestamp.adoc new file mode 100644 index 00000000..9b19709d --- /dev/null +++ b/docs/ref/stat/nng_stat_timestamp.adoc @@ -0,0 +1,34 @@ +## nng_stat_timestamp + +Get statistic timestamp. + +### Synopsis + +```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:../util/nng_clock.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. + +### See Also + +xref:nng_stats_get.adoc[nng_stats_get], +xref:nng_stat_value.adoc[nng_stat_value], +xref:../util/nng_clock.adoc[nng_clock] diff --git a/docs/ref/stat/nng_stat_type.adoc b/docs/ref/stat/nng_stat_type.adoc new file mode 100644 index 00000000..8d94f5f4 --- /dev/null +++ b/docs/ref/stat/nng_stat_type.adoc @@ -0,0 +1,66 @@ +## nng_stat_type + +Get statistic type. + +### 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 +}; + +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 (seexref:nng_stat_child.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.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.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.adoc[`nng_stat_unit`] function will provide more detail about the units measured by the static. + +### Return Values + +The statistic type for _stat_. + +### See Also + +xref:nng_stats_get.adoc[nng_stats_get], +xref:nng_stat_string.adoc[nng_stat_string], +xref:nng_stat_unit.adoc[nng_stat_unit], +xref:nng_stat_value.adoc[nng_stat_value] diff --git a/docs/ref/stat/nng_stat_unit.adoc b/docs/ref/stat/nng_stat_unit.adoc new file mode 100644 index 00000000..61c1573a --- /dev/null +++ b/docs/ref/stat/nng_stat_unit.adoc @@ -0,0 +1,59 @@ +## nng_stat_unit + +Get statistic unit. + +### Synopsis + +```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.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. + +((`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.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_. + +### See Also + +xref:nng_stats_get.adoc[nng_stats_get], +xref:nng_stat_name.adoc[nng_stat_name], +xref:nng_stat_type.adoc[nng_stat_type], +xref:nng_stat_value.adoc[nng_stat_value] diff --git a/docs/ref/stat/nng_stat_value.adoc b/docs/ref/stat/nng_stat_value.adoc new file mode 100644 index 00000000..5e4da8f9 --- /dev/null +++ b/docs/ref/stat/nng_stat_value.adoc @@ -0,0 +1,30 @@ +## nng_stat_value + +Get statistic numeric value. + +### Synopsis + +```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.adoc[`nng_stat_type`] for a description of statistic types. + +### Return Values + +The numeric value associated with _stat_. + +### See Also + +xref:nng_stats_get.adoc[nng_stats_get], +xref:nng_stat_bool.adoc[nng_stat_bool], +xref:nng_stat_type.adoc[nng_stat_type], +xref:nng_stat_unit.adoc[nng_stat_unit] -- cgit v1.2.3-70-g09d2