From d83b96faeb02d7a3574e63880141d6b23f31ced1 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore 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/CMakeLists.txt | 12 +++++ docs/man/libnng.3.adoc | 19 ++++++++ docs/man/nng_msg.5.adoc | 9 ---- docs/man/nng_stat.5.adoc | 78 +++++++++++++++++++++++++++++++ docs/man/nng_stat_child.3.adoc | 51 ++++++++++++++++++++ docs/man/nng_stat_desc.3.adoc | 52 +++++++++++++++++++++ docs/man/nng_stat_name.3.adoc | 47 +++++++++++++++++++ docs/man/nng_stat_next.3.adoc | 48 +++++++++++++++++++ docs/man/nng_stat_string.3.adoc | 51 ++++++++++++++++++++ docs/man/nng_stat_timestamp.3.adoc | 60 ++++++++++++++++++++++++ docs/man/nng_stat_type.3.adoc | 95 ++++++++++++++++++++++++++++++++++++++ docs/man/nng_stat_unit.3.adoc | 86 ++++++++++++++++++++++++++++++++++ docs/man/nng_stat_value.3.adoc | 51 ++++++++++++++++++++ docs/man/nng_stats_free.3.adoc | 51 ++++++++++++++++++++ docs/man/nng_stats_get.3.adoc | 86 ++++++++++++++++++++++++++++++++++ 15 files changed, 787 insertions(+), 9 deletions(-) create mode 100644 docs/man/nng_stat.5.adoc create mode 100644 docs/man/nng_stat_child.3.adoc create mode 100644 docs/man/nng_stat_desc.3.adoc create mode 100644 docs/man/nng_stat_name.3.adoc create mode 100644 docs/man/nng_stat_next.3.adoc create mode 100644 docs/man/nng_stat_string.3.adoc create mode 100644 docs/man/nng_stat_timestamp.3.adoc create mode 100644 docs/man/nng_stat_type.3.adoc create mode 100644 docs/man/nng_stat_unit.3.adoc create mode 100644 docs/man/nng_stat_value.3.adoc create mode 100644 docs/man/nng_stats_free.3.adoc create mode 100644 docs/man/nng_stats_get.3.adoc (limited to 'docs') diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt index 21651ba5..e39f2da3 100644 --- a/docs/man/CMakeLists.txt +++ b/docs/man/CMakeLists.txt @@ -151,6 +151,17 @@ if (NNG_ENABLE_DOC) nng_setopt nng_sleep_aio nng_socket_id + nng_stats_free + nng_stats_get + nng_stat_child + nng_stat_desc + nng_stat_name + nng_stat_next + nng_stat_string + nng_stat_timestamp + nng_stat_type + nng_stat_unit + nng_stat_value nng_strdup nng_strerror nng_strfree @@ -305,6 +316,7 @@ if (NNG_ENABLE_DOC) nng_sockaddr_ipc nng_sockaddr_zt nng_socket + nng_stat ) set(NNG_MAN7 diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 3e3037f9..299b73ef 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -222,6 +222,25 @@ concurrent applications. |<>|set context option |=== +=== Statistics + +The following functions provide access to statistics which can be used +to observe program behaviors and as an aid in troubleshooting. + +|=== +|<>|get child statistic +|<>|get statistic description +|<>|get statistic name +|<>|get next statistic +|<>|get statistic string value +|<>|get statistic timestamp +|<>|get statistic type +|<>|get statistic unit +|<>|get statistic value +|<>|free statistics +|<>|get statistics +|=== + === URL Object Common functionality is supplied for parsing and handling diff --git a/docs/man/nng_msg.5.adoc b/docs/man/nng_msg.5.adoc index 45b04e03..69789560 100644 --- a/docs/man/nng_msg.5.adoc +++ b/docs/man/nng_msg.5.adoc @@ -44,15 +44,6 @@ automatic data conversion, and removing data from the beginning or end. These functions are designed to try to avoid copying message contents by making use of scratch areas at the beginning and end of the message. -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. - == SEE ALSO [.text-left] 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. +// Copyright 2018 Capitar IT Group BV +// +// 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 + +typedef struct nng_stat nng_stat; +---- + +== DESCRIPTION + +An `nng_stat`(((statistic))) represents a statistic. +All statistics have names (`<>`) and +descriptions (`<>`), and are +typed (`<>`). + +Most statistics are numeric, +and thus carry a value (`<>`) +and frequently also a unit that the value measures (`<>`). + +Some statistics however, are simply strings (`<>`), +and thus carry no numeric value. + +Statistics are organized as a tree, and any given statistic can have siblings +(`<>`). +Note however that generally only `NNG_STAT_SCOPE` statistics, which are +act as placeholders in the tree (and carry no value), +will have children (`<>`). + +A tree of statistics is collected using `<>`, +and can be freed when no longer needed with `<>`. +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 +`<>`, 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] +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_stat_child.3.adoc b/docs/man/nng_stat_child.3.adoc new file mode 100644 index 00000000..c77e7135 --- /dev/null +++ b/docs/man/nng_stat_child.3.adoc @@ -0,0 +1,51 @@ += nng_version(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_child - get child statistic + +== SYNOPSIS + +[source, c] +---- +#include + +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 `<>`) +of `NNG_STAT_SCOPE` will have children. + +== RETURN VALUES + +The first child statistic of _parent_, or NULL if _parent_ has no children. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_stat_desc.3.adoc b/docs/man/nng_stat_desc.3.adoc new file mode 100644 index 00000000..3f184366 --- /dev/null +++ b/docs/man/nng_stat_desc.3.adoc @@ -0,0 +1,52 @@ += nng_version(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_desc - get statistic description + +== SYNOPSIS + +[source, c] +---- +#include + +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_. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_stat_name.3.adoc b/docs/man/nng_stat_name.3.adoc new file mode 100644 index 00000000..aaf854f5 --- /dev/null +++ b/docs/man/nng_stat_name.3.adoc @@ -0,0 +1,47 @@ += nng_version(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_name - get statistic name + +== SYNOPSIS + +[source, c] +---- +#include + +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_. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<> diff --git a/docs/man/nng_stat_next.3.adoc b/docs/man/nng_stat_next.3.adoc new file mode 100644 index 00000000..d2ae24a4 --- /dev/null +++ b/docs/man/nng_stat_next.3.adoc @@ -0,0 +1,48 @@ += nng_version(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_next - get next statistic + +== SYNOPSIS + +[source, c] +---- +#include + +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. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_stat_string.3.adoc b/docs/man/nng_stat_string.3.adoc new file mode 100644 index 00000000..9f44b5b7 --- /dev/null +++ b/docs/man/nng_stat_string.3.adoc @@ -0,0 +1,51 @@ += nng_version(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_string - get statistic string value + +== SYNOPSIS + +[source, c] +---- +#include + +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 `<>`). + +If the statistic is not of type `NNG_STAT_STRING`, then `NULL` will be returned. + +== RETURN VALUES + +The string value associated with _stat_, or `NULL` if the statistic is not +a string type. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_stat_timestamp.3.adoc b/docs/man/nng_stat_timestamp.3.adoc new file mode 100644 index 00000000..f23d8720 --- /dev/null +++ b/docs/man/nng_stat_timestamp.3.adoc @@ -0,0 +1,60 @@ += nng_version(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_timestamp - get statistic timestamp + +== SYNOPSIS + +[source, c] +---- +#include + +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 +`<>` supplementation 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. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_stat_type.3.adoc b/docs/man/nng_stat_type.3.adoc new file mode 100644 index 00000000..d1b1586d --- /dev/null +++ b/docs/man/nng_stat_type.3.adoc @@ -0,0 +1,95 @@ += nng_version(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_value - get statistic value + +== SYNOPSIS + +[source, c] +---- +#include + +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 it's own. +Instead it is a parent node with child statistics (see +`<>`.) + +((`NNG_STAT_LEVEL`)):: +This is a numeric statistic, but it's 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 `<>` function +should be used to obtain the value. + +((`NNG_STAT_BOOLEAN`)):: +This is a boolean value. +The `<>` 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 +`<>` function will provide more +detail about the units measured by the static. + +== RETURN VALUES + +The statistic type for _stat_. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_stat_unit.3.adoc b/docs/man/nng_stat_unit.3.adoc new file mode 100644 index 00000000..cb9bb7cf --- /dev/null +++ b/docs/man/nng_stat_unit.3.adoc @@ -0,0 +1,86 @@ += nng_version(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_value - get statistic value + +== SYNOPSIS + +[source, c] +---- +#include + +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 `<>`) of the statistic. + +((`NNG_UNIT_BYTES`)):: +The statistic is a count of bytes. + +((`NNG_UNIT_MESSAGES`)):: +The statistic is a count of messages. +Typically, one message corresponds to a single `<>` structure. + +((`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 `<>`), 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_. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_stat_value.3.adoc b/docs/man/nng_stat_value.3.adoc new file mode 100644 index 00000000..2864ba30 --- /dev/null +++ b/docs/man/nng_stat_value.3.adoc @@ -0,0 +1,51 @@ += nng_version(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_value - get statistic value + +== SYNOPSIS + +[source, c] +---- +#include + +typedef struct nng_stat nng_stat; + +uint64_t nng_stat_string(nng_stat *stat); +---- + +== DESCRIPTION + +The `nng_stat_value()` function returns a numeric value for the statistic _stat_. +If the statistic has a boolean value, then zero is returned for `false`, and +one is returned for `true`. +Otherwise, if the string is not of numeric type, then zero is returned. +See `<>` for a description of statistic types. + +== RETURN VALUES + +The numeric or boolean value associated with _stat_. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_stats_free.3.adoc b/docs/man/nng_stats_free.3.adoc new file mode 100644 index 00000000..3b5c7457 --- /dev/null +++ b/docs/man/nng_stats_free.3.adoc @@ -0,0 +1,51 @@ += nng_free(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_stats_free - free statistics snapshot + +== SYNOPSIS + +[source, c] +---- +#include + +typedef nng_stat nng_stat; + +void nng_stats_free(nng_stat *); +---- + +== DESCRIPTION + +The `nng_stats_free()` function deallocates a statistics snapshot +previously collected with +`<>`. +After calling this, all values associated with the snapshot are +invalidated. + +IMPORTANT: Only the top of the collected statistics tree can be +freed using this function. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +<>, +<>, +<> diff --git a/docs/man/nng_stats_get.3.adoc b/docs/man/nng_stats_get.3.adoc new file mode 100644 index 00000000..caf91dc3 --- /dev/null +++ b/docs/man/nng_stats_get.3.adoc @@ -0,0 +1,86 @@ += nng_alloc(3) +// +// Copyright 2018 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// +// 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_stats_get - get statistics snapshot + +== SYNOPSIS + +[source, c] +---- +#include + +typedef struct nng_stat nng_stat; + +int nng_stats_get(nng_stat *statsp) +---- + +== DESCRIPTION + +The `nng_stat_get()` function attempts to obtain a snapshot of all the +various diagnostic statistics that are present in the system. + +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. + +The `<>` and +`<>` function can be used to +iterate over the the tree. + +When no longer needed, the statistics can be freed with the +`<>` function, but that +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. + +NOTE: The names, values, and semantics of statistics provided may change +from release to release. +These are provided for informational and debugging use only, and applications +should not rely on the presence, names, or meanings of any individual statistics. + +== RETURN VALUES + +This function returns a pointer to the allocated memory on success, +and `NULL` otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOMEM`:: Insufficient free memory to collect statistics. +`NNG_ENOTSUP`:: Statistics are not supported (compile time option). + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> -- cgit v1.2.3-70-g09d2