= nng_stat(5)

// Copyright 2019 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 (xref:nng_stat_name.3.adoc[`nng_stat_name()`]) and
descriptions (xref:nng_stat_desc.3.adoc[`nng_stat_desc()`]), and are
typed (xref:nng_stat_type.3.adoc[`nng_stat_type()`]).

Most statistics are numeric,
and thus carry a value (xref:nng_stat_value.3.adoc[`nng_stat_value()`])
and frequently also a unit that the value measures (xref:nng_stat_unit.3.adoc[`nng_stat_unit()`]).

Some statistics however, are simply strings (xref:nng_stat_string.3.adoc[`nng_stat_string()`]),
and thus carry no numeric value.

Statistics are organized as a tree, and any given statistic can have siblings
(xref:nng_stat_next.3.adoc[`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 (xref:nng_stat_child.3.adoc[`nng_stat_child()`]).

A tree of statistics is collected using xref:nng_stats_get.3.adoc[`nng_stats_get()`],
and can be freed when no longer needed with xref:nng_stats_free.3.adoc[`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
xref:nng_stat_timestamp.3.adoc[`nng_stat_timestamp()`], 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]
xref:libnng.3.adoc[libnng(3)],
xref:nng_stats_free.3.adoc[nng_stats_free(3)],
xref:nng_stats_get.3.adoc[nng_stats_get(3)],
xref:nng_stat_child.3.adoc[nng_stat_child(3)],
xref:nng_stat_desc.3.adoc[nng_stat_desc(3)],
xref:nng_stat_find.3.adoc[nng_stat_find(3)],
xref:nng_stat_find_dialer.3.adoc[nng_stat_find_dialer(3)],
xref:nng_stat_find_listener.3.adoc[nng_stat_find_listener(3)],
xref:nng_stat_find_socket.3.adoc[nng_stat_find_socket(3)],
xref:nng_stat_name.3.adoc[nng_stat_name(3)],
xref:nng_stat_next.3.adoc[nng_stat_next(3)],
xref:nng_stat_string.3.adoc[nng_stat_string(3)],
xref:nng_stat_timestamp.3.adoc[nng_stat_timestamp(3)],
xref:nng_stat_type.3.adoc[nng_stat_type(3)],
xref:nng_stat_unit.3.adoc[nng_stat_unit(3)],
xref:nng_stat_value.3.adoc[nng_stat_value(3)],
xref:nng.7.adoc[nng(7)]