Converted stats pages

14 files changed, 505 insertions, 0 deletions

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 <nng/nng.h>
+
+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 <nng/nng.h>
+
+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 <nng/nng.h>
+
+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 <nng/nng.h>
+
+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 <nng/nng.h>
+
+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 <nng/nng.h>
+
+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 <nng/nng.h>
+
+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 <nng/nng.h>
+
+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 <nng/nng.h>
+
+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 <nng/nng.h>
+
+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 <nng/nng.h>
+
+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 <nng/nng.h>
+
+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 <nng/nng.h>
+
+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 <nng/nng.h>
+
+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]