Statistics

To facilitate debugging and support situations, the NNG library provides for collection and reporting of numerous statistics.

These statistics are organized in a tree, and include both values, and metadata describing the statistics. In order to be efficient and minimize the impact of maintaining statistics, an explicit snapshot of statistics must be taken, and that snapshot can then be processed.

Statistic Structure

typedef struct nng_stat nng_stat;

The nng_stat structure represents a statistic, which is a single value collected at a specific point in time.

This structure has meta-data describing the value, the value itself, and links to any sibling or child statistics.

Collecting a Snapshot

int nng_stats_get(nng_stat **statsp);

The nng_stats_get function takes a snapshot of the statistics for the system and returns it through the pointer statsp. This function may return NNG_ENOMEM if memory is exhausted, or NNG_ENOTSUP if the statistics support is not enabled in the build, but is otherwise expected to return zero.

Freeing a Snapshot

void nng_stats_free(nng_stat *stat);

The nng_stats_free function deallocates the snapshot referenced by stat.

Traversing the Tree

const nng_stat *nng_stat_child(const nng_stat *stat);
const nng_stat *nng_stat_next(const nng_stat *stat);

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

const nng_stat *nng_stat_find(const nng_stat *stat, const char *name);
const nng_stat *nng_stat_find_dialer(const nng_stat *stat, nng_dialer dialer);
const nng_stat *nng_stat_find_listener(const nng_stat *stat, nng_dialer listener);
const nng_stat *nng_stat_find_socket(const nng_stat *stat, nng_dialer socket);

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, dialer, or 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. If no such statistic can be found, then they return NULL. These functions should be provided the root of the statistic tree, in order to ensure that they can find the desired object.

Statistic Identification

const char *nng_stat_name(const nng_stat *stat);
const char *nng_stat_desc(const nng_stat *stat);

Every statistic has a name, returned by nng_stat_name, and a description, returned by nng_stat_desc. Descriptions are human-readable text, which might be useful for display.

Statistic Type

int nng_stat_type(const nng_stat *stat);

The function nng_stat_type returns the type of the statistic. The type of a statistic determines the nature of the value, and which function can be used to obtain that value.

• 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.

• 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.

• 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.

• NNG_STAT_STRING: The statistic is a string, such as a name. 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_STAT_BOOLEAN: The value of the statistic is a truth value (either true or false) and can be obtained with nng_stat_bool.

• 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 be fixed for the life of the statistic.

Statistic Value

uint64_t nng_stat_value(const nng_stat *stat);
const char *nng_stat_string(const nng_stat *stat);
bool nng_stat_bool(const nng_stat *stat);

These functions return the value associated with the statistic.

The nng_stat_value function returns the the numeric value for the statistic stat of type NNG_STAT_COUNTER, NNG_STAT_LEVEL, or NNG_STAT_ID. If stat is not one of these types, then it returns zero.

The nng_stat_bool function returns the Boolean value (either true or false) for the statistic stat of type NNG_STAT_BOOLEAN. If the statistics is not of this type, then it returns false.

The nng_stat_string function returns a pointer to a string value for the statistic stat, of type NNG_STAT_STRING. This string will remain valud until the snapshot that stat was collected with is deallocated with nng_stats_free. If the statistic is not of type NNG_STAT_STRING, then NULL is returned.

Statistic Units

int nng_stat_unit(const nng_stat *stat);

For statistics of type NNG_STAT_COUNTER or NNG_STAT_LEVEL, it is often useful to know what that quantity being reported 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.

Statistic Timestamp

uint64_t nng_stat_timestamp(const nng_stat *stat);

Statistics have a timestamp indicating when the value was sampled, obtained via 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.

See Also

nng_clock