1 files changed, 107 insertions, 0 deletions
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 <nng/nng.h>
+
+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