1 files changed, 110 insertions, 0 deletions
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 <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
+};
+
+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