From d83b96faeb02d7a3574e63880141d6b23f31ced1 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Wed, 22 Aug 2018 08:56:53 -0700
Subject: fixes #4 Statistics support

This introduces new public APIs for obtaining statistics,
and adds some generic stats for dialers, listeners, pipes, and
sockets.  Also added are stats for inproc and pairv1 protocol.

The other protocols and transports will have stats added
incrementally as time goes on.

A simple test program, and man pages are provided for this.
Start by looking at nng_stat(5).

Statistics does have some impact, and they can be disabled by
using the advanced NNG_ENABLE_STATS (setting it to OFF, it's
ON by default) if you need to build a minimized configuration.
---
 docs/man/nng_stat.5.adoc | 78 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 docs/man/nng_stat.5.adoc

(limited to 'docs/man/nng_stat.5.adoc')

diff --git a/docs/man/nng_stat.5.adoc b/docs/man/nng_stat.5.adoc
new file mode 100644
index 00000000..8c8a5746
--- /dev/null
+++ b/docs/man/nng_stat.5.adoc
@@ -0,0 +1,78 @@
+= nng_socket(5)
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+//
+// 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 <nng/nng.h>
+
+typedef struct nng_stat nng_stat;
+----
+
+== DESCRIPTION
+
+An `nng_stat`(((statistic))) represents a statistic.
+All statistics have names (`<<nng_stat_name.3#,nng_stat_name()>>`) and
+descriptions (`<<nng_stat_desc.3#,nng_stat_desc()>>`), and are
+typed (`<<nng_stat_type.3#,nng_stat_type()>>`).
+
+Most statistics are numeric,
+and thus carry a value (`<<nng_stat_value.3#,nng_stat_value()>>`)
+and frequently also a unit that the value measures (`<<nng_stat_unit.3#,nng_stat_unit()>>`).
+
+Some statistics however, are simply strings (`<<nng_stat_string.3#,nng_stat_string()>>`),
+and thus carry no numeric value.
+
+Statistics are organized as a tree, and any given statistic can have siblings
+(`<<nng_stat_next.3#,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 (`<<nng_stat_child.3#,nng_stat_child()>>`).
+
+A tree of statistics is collected using `<<nng_stats_get.3#,nng_stats_get()>>`,
+and can be freed when no longer needed with `<<nng_stats_free.3#,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
+`<<nng_stat_timestamp.3#,nng_stat_timestap()>>`, 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]
+<<libnng.3#,libnng(3)>>,
+<<nng_stats_free.3#,nng_stats_free(3)>>,
+<<nng_stats_get.3#,nng_stats_get(3)>>,
+<<nng_stat_child.3#,nng_stat_child(3)>>,
+<<nng_stat_desc.3#,nng_stat_desc(3)>>,
+<<nng_stat_name.3#,nng_stat_name(3)>>,
+<<nng_stat_next.3#,nng_stat_next(3)>>,
+<<nng_stat_string.3#,nng_stat_string(3)>>,
+<<nng_stat_timestamp.3#,nng_stat_timestamp(3)>>,
+<<nng_stat_type.3#,nng_stat_type(3)>>,
+<<nng_stat_unit.3#,nng_stat_unit(3)>>,
+<<nng_stat_value.3#,nng_stat_value(3)>>,
+<<nng.7#,nng(7)>>
-- 
cgit v1.2.3-70-g09d2

