diff options
Diffstat (limited to 'src/core/stat_item.c')
| -rw-r--r-- | src/core/stat_item.c | 463 |
1 files changed, 463 insertions, 0 deletions
diff --git a/src/core/stat_item.c b/src/core/stat_item.c new file mode 100644 index 00000000..804972bf --- /dev/null +++ b/src/core/stat_item.c @@ -0,0 +1,463 @@ +/*! \file stat_item.c + * utility routines for keeping statistical values */ +/* + * (C) 2009-2010 by Harald Welte <laforge@gnumonks.org> + * (C) 2015 by sysmocom - s.f.m.c. GmbH + * + * All Rights Reserved + * + * SPDX-License-Identifier: GPL-2.0+ + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + */ + +/*! \addtogroup osmo_stat_item + * @{ + * + * This osmo_stat_item module adds instrumentation capabilities to + * gather measurement and statistical values in a similar fashion to + * what we have as \ref osmo_counter_group. + * + * As opposed to counters, osmo_stat_item do not increment but consist + * of a configurable-sized FIFO, which can store not only the current + * (most recent) value, but also historic values. + * + * The only supported value type is an int32_t. + * + * Getting values from osmo_stat_item is usually done at a high level + * through the stats API (stats.c). It uses item->stats_next_id to + * store what has been sent to all enabled reporters. It is also + * possible to read from osmo_stat_item directly, without modifying + * its state, by storing next_id outside of osmo_stat_item. + * + * Each value stored in the FIFO of an osmo_stat_item has an associated + * value_id. The value_id is increased with each value, so (until the + * counter wraps) more recent values will have higher values. + * + * When a new value is set, the oldest value in the FIFO gets silently + * overwritten. Lost values are skipped when getting values from the + * item. + * + */ + +/* Struct overview: + * + * Group and item descriptions: + * Each group description exists once as osmo_stat_item_group_desc, + * each such group description lists N osmo_stat_item_desc, i.e. describes N stat items. + * + * Actual stats: + * The global osmo_stat_item_groups llist contains all group instances, each points at a group description. + * This list mixes all types of groups in a single llist, where each instance points at its group desc and has an index. + * There are one or more instances of each group, each storing stats for a distinct object (for example, one description + * for a BTS group, and any number of BTS instances with independent stats). A group is identified by a group index nr + * and possibly also a given name for that particular index (e.g. in osmo-mgw, a group instance is named + * "virtual-trunk-0" and can be looked up by that name instead of its more or less arbitrary group index number). + * + * Each group instance contains one osmo_stat_item instance per global stat item description. + * Each osmo_stat_item keeps track of the values for the current reporting period (min, last, max, sum, n), + * and also stores the set of values reported at the end of the previous reporting period. + * + * const osmo_stat_item_group_desc foo + * +-- group_name_prefix = "foo" + * +-- item_desc[] (array of osmo_stat_item_desc) + * +-- osmo_stat_item_desc bar + * | +-- name = "bar" + * | +-- description + * | +-- unit + * | +-- default_value + * | + * +-- osmo_stat_item_desc: baz + * +-- ... + * + * const osmo_stat_item_group_desc moo + * +-- group_name_prefix = "moo" + * +-- item_desc[] + * +-- osmo_stat_item_desc goo + * | +-- name = "goo" + * | +-- description + * | +-- unit + * | +-- default_value + * | + * +-- osmo_stat_item_desc: loo + * +-- ... + * + * osmo_stat_item_groups (llist of osmo_stat_item_group) + * | + * +-- group: foo[0] + * | +-- desc --> osmo_stat_item_group_desc foo + * | +-- idx = 0 + * | +-- name = NULL (no given name for this group instance) + * | +-- items[] + * | | + * | [0] --> osmo_stat_item instance for "bar" + * | | +-- desc --> osmo_stat_item_desc bar (see above) + * | | +-- value.{min, last, max, n, sum} + * | | +-- reported.{min, last, max, n, sum} + * | | + * | [1] --> osmo_stat_item instance for "baz" + * | | +-- desc --> osmo_stat_item_desc baz + * | | +-- value.{min, last, max, n, sum} + * | | +-- reported.{min, last, max, n, sum} + * | . + * | : + * | + * +-- group: foo[1] + * | +-- desc --> osmo_stat_item_group_desc foo + * | +-- idx = 1 + * | +-- name = "special-foo" (instance can be looked up by this index-name) + * | +-- items[] + * | | + * | [0] --> osmo_stat_item instance for "bar" + * | | +-- desc --> osmo_stat_item_desc bar + * | | +-- value.{min, last, max, n, sum} + * | | +-- reported.{min, last, max, n, sum} + * | | + * | [1] --> osmo_stat_item instance for "baz" + * | | +-- desc --> osmo_stat_item_desc baz + * | | +-- value.{min, last, max, n, sum} + * | | +-- reported.{min, last, max, n, sum} + * | . + * | : + * | + * +-- group: moo[0] + * | +-- desc --> osmo_stat_item_group_desc moo + * | +-- idx = 0 + * | +-- name = NULL + * | +-- items[] + * | | + * | [0] --> osmo_stat_item instance for "goo" + * | | +-- desc --> osmo_stat_item_desc goo + * | | +-- value.{min, last, max, n, sum} + * | | +-- reported.{min, last, max, n, sum} + * | | + * | [1] --> osmo_stat_item instance for "loo" + * | | +-- desc --> osmo_stat_item_desc loo + * | | +-- value.{min, last, max, n, sum} + * | | +-- reported.{min, last, max, n, sum} + * | . + * | : + * . + * : + * + */ + +#include <stdint.h> +#include <string.h> + +#include <osmocom/core/utils.h> +#include <osmocom/core/linuxlist.h> +#include <osmocom/core/logging.h> +#include <osmocom/core/talloc.h> +#include <osmocom/core/timer.h> +#include <osmocom/core/stat_item.h> + +#include <stat_item_internal.h> + +/*! global list of stat_item groups */ +static LLIST_HEAD(osmo_stat_item_groups); + +/*! talloc context from which we allocate */ +static void *tall_stat_item_ctx; + +/*! Allocate a new group of counters according to description. + * Allocate a group of stat items described in \a desc from talloc context \a ctx, + * giving the new group the index \a idx. + * \param[in] ctx \ref talloc context + * \param[in] desc Statistics item group description + * \param[in] idx Index of new stat item group + */ +struct osmo_stat_item_group *osmo_stat_item_group_alloc(void *ctx, + const struct osmo_stat_item_group_desc *group_desc, + unsigned int idx) +{ + unsigned int group_size; + unsigned int item_idx; + struct osmo_stat_item *items; + + struct osmo_stat_item_group *group; + + group_size = sizeof(struct osmo_stat_item_group) + + group_desc->num_items * sizeof(struct osmo_stat_item *); + + if (!ctx) + ctx = tall_stat_item_ctx; + + group = talloc_zero_size(ctx, group_size); + if (!group) + return NULL; + + group->desc = group_desc; + group->idx = idx; + + items = talloc_array(group, struct osmo_stat_item, group_desc->num_items); + OSMO_ASSERT(items); + for (item_idx = 0; item_idx < group_desc->num_items; item_idx++) { + struct osmo_stat_item *item = &items[item_idx]; + const struct osmo_stat_item_desc *item_desc = &group_desc->item_desc[item_idx]; + group->items[item_idx] = item; + *item = (struct osmo_stat_item){ + .desc = item_desc, + .value = { + .n = 0, + .last = item_desc->default_value, + .min = item_desc->default_value, + .max = item_desc->default_value, + .sum = 0, + }, + }; + } + + llist_add(&group->list, &osmo_stat_item_groups); + return group; +} + +/*! Free the memory for the specified group of stat items */ +void osmo_stat_item_group_free(struct osmo_stat_item_group *grp) +{ + if (!grp) + return; + + llist_del(&grp->list); + talloc_free(grp); +} + +/*! Get statistics item from group, identified by index idx + * \param[in] grp Rate counter group + * \param[in] idx Index of the counter to retrieve + * \returns rate counter requested + */ +struct osmo_stat_item *osmo_stat_item_group_get_item(struct osmo_stat_item_group *grp, unsigned int idx) +{ + return grp->items[idx]; +} + +/*! Set a name for the statistics item group to be used instead of index value + at report time. + * \param[in] statg Statistics item group + * \param[in] name Name identifier to assign to the statistics item group + */ +void osmo_stat_item_group_set_name(struct osmo_stat_item_group *statg, const char *name) +{ + osmo_talloc_replace_string(statg, &statg->name, name); +} + +/*! Increase the stat_item to the given value. + * This function adds a new value for the given stat_item at the end of + * the FIFO. + * \param[in] item The stat_item whose \a value we want to set + * \param[in] value The numeric value we want to store at end of FIFO + */ +void osmo_stat_item_inc(struct osmo_stat_item *item, int32_t value) +{ + osmo_stat_item_set(item, item->value.last + value); +} + +/*! Descrease the stat_item to the given value. + * This function adds a new value for the given stat_item at the end of + * the FIFO. + * \param[in] item The stat_item whose \a value we want to set + * \param[in] value The numeric value we want to store at end of FIFO + */ +void osmo_stat_item_dec(struct osmo_stat_item *item, int32_t value) +{ + osmo_stat_item_set(item, item->value.last - value); +} + +/*! Set the a given stat_item to the given value. + * This function adds a new value for the given stat_item at the end of + * the FIFO. + * \param[in] item The stat_item whose \a value we want to set + * \param[in] value The numeric value we want to store at end of FIFO + */ +void osmo_stat_item_set(struct osmo_stat_item *item, int32_t value) +{ + item->value.last = value; + if (item->value.n == 0) { + /* No values recorded yet, clamp min and max to this first value. */ + item->value.min = item->value.max = value; + /* Overwrite any cruft remaining in value.sum */ + item->value.sum = value; + item->value.n = 1; + } else { + item->value.min = OSMO_MIN(item->value.min, value); + item->value.max = OSMO_MAX(item->value.max, value); + item->value.sum += value; + item->value.n++; + } +} + +/*! Indicate that a reporting period has elapsed, and prepare the stat item for a new period of collecting min/max/avg. + * \param item Stat item to flush. + */ +void osmo_stat_item_flush(struct osmo_stat_item *item) +{ + item->reported = item->value; + + /* Indicate a new reporting period: no values have been received, but the previous value.last remains unchanged + * for the case that an entire period elapses without a new value appearing. */ + item->value.n = 0; + item->value.sum = 0; + + /* Also for the case that an entire period elapses without any osmo_stat_item_set(), put the min and max to the + * last value. As soon as one osmo_stat_item_set() occurs, these are both set to the new value (when n is still + * zero from above). */ + item->value.min = item->value.max = item->value.last; +} + +/*! Initialize the stat item module. Call this once from your program. + * \param[in] tall_ctx Talloc context from which this module allocates */ +int osmo_stat_item_init(void *tall_ctx) +{ + tall_stat_item_ctx = tall_ctx; + + return 0; +} + +/*! Search for item group based on group name and index + * \param[in] name Name of stats_item_group we want to find + * \param[in] idx Index of the group we want to find + * \returns pointer to group, if found; NULL otherwise */ +struct osmo_stat_item_group *osmo_stat_item_get_group_by_name_idx( + const char *name, const unsigned int idx) +{ + struct osmo_stat_item_group *statg; + + llist_for_each_entry(statg, &osmo_stat_item_groups, list) { + if (!statg->desc) + continue; + + if (!strcmp(statg->desc->group_name_prefix, name) && + statg->idx == idx) + return statg; + } + return NULL; +} + +/*! Search for item group based on group name and index's name. + * \param[in] name Name of stats_item_group we want to find. + * \param[in] idx_name Index of the group we want to find, by the index's name (osmo_stat_item_group->name). + * \returns pointer to group, if found; NULL otherwise. */ +struct osmo_stat_item_group *osmo_stat_item_get_group_by_name_idxname(const char *group_name, const char *idx_name) +{ + struct osmo_stat_item_group *statg; + + llist_for_each_entry(statg, &osmo_stat_item_groups, list) { + if (!statg->desc || !statg->name) + continue; + if (strcmp(statg->desc->group_name_prefix, group_name)) + continue; + if (strcmp(statg->name, idx_name)) + continue; + return statg; + } + return NULL; +} + +/*! Search for item based on group + item name + * \param[in] statg group in which to search for the item + * \param[in] name name of item to search within \a statg + * \returns pointer to item, if found; NULL otherwise */ +const struct osmo_stat_item *osmo_stat_item_get_by_name( + const struct osmo_stat_item_group *statg, const char *name) +{ + int i; + const struct osmo_stat_item_desc *item_desc; + + if (!statg->desc) + return NULL; + + for (i = 0; i < statg->desc->num_items; i++) { + item_desc = &statg->desc->item_desc[i]; + + if (!strcmp(item_desc->name, name)) { + return statg->items[i]; + } + } + return NULL; +} + +/*! Iterate over all items in group, call user-supplied function on each + * \param[in] statg stat_item group over whose items to iterate + * \param[in] handle_item Call-back function, aborts if rc < 0 + * \param[in] data Private data handed through to \a handle_item + */ +int osmo_stat_item_for_each_item(struct osmo_stat_item_group *statg, + osmo_stat_item_handler_t handle_item, void *data) +{ + int rc = 0; + int i; + + for (i = 0; i < statg->desc->num_items; i++) { + struct osmo_stat_item *item = statg->items[i]; + rc = handle_item(statg, item, data); + if (rc < 0) + return rc; + } + + return rc; +} + +/*! Iterate over all stat_item groups in system, call user-supplied function on each + * \param[in] handle_group Call-back function, aborts if rc < 0 + * \param[in] data Private data handed through to \a handle_group + */ +int osmo_stat_item_for_each_group(osmo_stat_item_group_handler_t handle_group, void *data) +{ + struct osmo_stat_item_group *statg; + int rc = 0; + + llist_for_each_entry(statg, &osmo_stat_item_groups, list) { + rc = handle_group(statg, data); + if (rc < 0) + return rc; + } + + return rc; +} + +/*! Get the last (freshest) value. */ +int32_t osmo_stat_item_get_last(const struct osmo_stat_item *item) +{ + return item->value.last; +} + +/*! Remove all values of a stat item + * \param[in] item stat item to reset + */ +void osmo_stat_item_reset(struct osmo_stat_item *item) +{ + item->value.sum = 0; + item->value.n = 0; + item->value.last = item->value.min = item->value.max = item->desc->default_value; +} + +/*! Reset all osmo stat items in a group + * \param[in] statg stat item group to reset + */ +void osmo_stat_item_group_reset(struct osmo_stat_item_group *statg) +{ + int i; + + for (i = 0; i < statg->desc->num_items; i++) { + struct osmo_stat_item *item = statg->items[i]; + osmo_stat_item_reset(item); + } +} + +/*! Return the description for an osmo_stat_item. */ +const struct osmo_stat_item_desc *osmo_stat_item_get_desc(struct osmo_stat_item *item) +{ + return item->desc; +} + +/*! @} */ |