diff options
| -rw-r--r-- | include/osmocom/core/stat_item.h | 46 | ||||
| -rw-r--r-- | src/stat_item.c | 85 |
2 files changed, 89 insertions, 42 deletions
diff --git a/include/osmocom/core/stat_item.h b/include/osmocom/core/stat_item.h index 4cee8a8b..260ffb1c 100644 --- a/include/osmocom/core/stat_item.h +++ b/include/osmocom/core/stat_item.h @@ -13,32 +13,34 @@ struct osmo_stat_item_desc; #define OSMO_STAT_ITEM_NOVALUE_ID 0 #define OSMO_STAT_ITEM_NO_UNIT NULL +/*! Individual entry in value FIFO */ struct osmo_stat_item_value { - int32_t id; - int32_t value; + int32_t id; /*!< identifier of value */ + int32_t value; /*!< actual value */ }; -/*! data we keep for each actual value */ +/*! data we keep for each actual item */ struct osmo_stat_item { + /*! back-reference to the item description */ const struct osmo_stat_item_desc *desc; /*! the index of the freshest value */ int32_t last_value_index; - /*! offset to the freshest value in the value fifo */ + /*! offset to the freshest value in the value FIFO */ int16_t last_offs; - /*! value fifo */ + /*! value FIFO */ struct osmo_stat_item_value values[0]; }; -/*! statistics value description */ +/*! Statistics item description */ struct osmo_stat_item_desc { const char *name; /*!< name of the item */ const char *description;/*!< description of the item */ const char *unit; /*!< unit of a value */ - unsigned int num_values;/*!< number of values to store */ - int32_t default_value; + unsigned int num_values;/*!< number of values to store in FIFO */ + int32_t default_value; /*!< default value */ }; -/*! description of a statistics value group */ +/*! Description of a statistics item group */ struct osmo_stat_item_group_desc { /*! The prefix to the name of all values in this group */ const char *group_name_prefix; @@ -46,9 +48,9 @@ struct osmo_stat_item_group_desc { const char *group_description; /*! The class to which this group belongs */ int class_id; - /*! The number of values in this group */ + /*! The number of values in this group (size of item_desc) */ const unsigned int num_items; - /*! Pointer to array of value names */ + /*! Pointer to array of value names, length as per num_items */ const struct osmo_stat_item_desc *item_desc; }; @@ -87,31 +89,13 @@ struct osmo_stat_item_group *osmo_stat_item_get_group_by_name_idx( const struct osmo_stat_item *osmo_stat_item_get_by_name( const struct osmo_stat_item_group *statg, const char *name); -/*! Retrieve the next value from the osmo_stat_item object. - * If a new value has been set, it is returned. The idx is used to decide - * which value to return. - * On success, *idx is updated to refer to the next unread value. If - * values have been missed due to FIFO overflow, *idx is incremented by - * (1 + num_lost). - * This way, the osmo_stat_item object can be kept stateless from the reader's - * perspective and therefore be used by several backends simultaneously. - * - * \param val the osmo_stat_item object - * \param idx identifies the next value to be read - * \param value a pointer to store the value - * \returns the increment of the index (0: no value has been read, - * 1: one value has been taken, - * (1+n): n values have been skipped, one has been taken) - */ int osmo_stat_item_get_next(const struct osmo_stat_item *item, int32_t *idx, int32_t *value); /*! Get the last (freshest) value */ static int32_t osmo_stat_item_get_last(const struct osmo_stat_item *item); -/*! Skip all values of the item and update idx accordingly */ int osmo_stat_item_discard(const struct osmo_stat_item *item, int32_t *idx); -/*! Skip all values of all items and update idx accordingly */ int osmo_stat_item_discard_all(int32_t *idx); typedef int (*osmo_stat_item_handler_t)( @@ -119,10 +103,6 @@ typedef int (*osmo_stat_item_handler_t)( typedef int (*osmo_stat_item_group_handler_t)(struct osmo_stat_item_group *, void *); -/*! Iteate over all items - * \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); diff --git a/src/stat_item.c b/src/stat_item.c index c073a3e2..cbcdebc6 100644 --- a/src/stat_item.c +++ b/src/stat_item.c @@ -1,5 +1,5 @@ /*! \file stat_item.c - * utility routines for keeping conters about events and the event rates. */ + * utility routines for keeping statistical values */ /* * (C) 2015 by Sysmocom s.f.m.c. GmbH * (C) 2009-2010 by Harald Welte <laforge@gnumonks.org> @@ -24,7 +24,31 @@ /*! \addtogroup osmo_stat_item * @{ - * \file stat_item.c */ + * + * 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 the osmo_stat_item does not modify its state to + * allow for multiple independent back-ends retrieving values (e.g. VTY + * and statd). + * + * Each value stored in the FIFO of an osmo_stat_item has an associated + * value_id. The value_id is derived from an application-wide globally + * incrementing counter, 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. + * + */ #include <stdint.h> #include <string.h> @@ -35,12 +59,17 @@ #include <osmocom/core/timer.h> #include <osmocom/core/stat_item.h> +/*! global list of stat_item groups */ static LLIST_HEAD(osmo_stat_item_groups); +/*! counter for assigning globally unique value identifiers */ static int32_t global_value_id = 0; +/*! talloc context from which we allocate */ static void *tall_stat_item_ctx; -/*! Allocate a new group of counters according to description +/*! 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 @@ -112,13 +141,19 @@ struct osmo_stat_item_group *osmo_stat_item_group_alloc(void *ctx, return group; } -/*! Free the memory for the specified group of counters */ +/*! Free the memory for the specified group of stat items */ void osmo_stat_item_group_free(struct osmo_stat_item_group *grp) { llist_del(&grp->list); talloc_free(grp); } +/*! 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->last_offs += 1; @@ -133,6 +168,22 @@ void osmo_stat_item_set(struct osmo_stat_item *item, int32_t value) item->values[item->last_offs].id = global_value_id; } +/*! Retrieve the next value from the osmo_stat_item object. + * If a new value has been set, it is returned. The idx is used to decide + * which value to return. + * On success, *idx is updated to refer to the next unread value. If + * values have been missed due to FIFO overflow, *idx is incremented by + * (1 + num_lost). + * This way, the osmo_stat_item object can be kept stateless from the reader's + * perspective and therefore be used by several backends simultaneously. + * + * \param val the osmo_stat_item object + * \param idx identifies the next value to be read + * \param value a pointer to store the value + * \returns the increment of the index (0: no value has been read, + * 1: one value has been taken, + * (1+n): n values have been skipped, one has been taken) + */ int osmo_stat_item_get_next(const struct osmo_stat_item *item, int32_t *next_idx, int32_t *value) { @@ -170,7 +221,7 @@ int osmo_stat_item_get_next(const struct osmo_stat_item *item, int32_t *next_idx return idx_delta; } -/*! Skip all values of this item and update idx accordingly */ +/*! Skip/discard all values of this item and update \a idx accordingly */ int osmo_stat_item_discard(const struct osmo_stat_item *item, int32_t *idx) { int discarded = item->values[item->last_offs].id + 1 - *idx; @@ -179,7 +230,7 @@ int osmo_stat_item_discard(const struct osmo_stat_item *item, int32_t *idx) return discarded; } -/*! Skip all values of all items and update idx accordingly */ +/*! Skip all values of all items and update \a idx accordingly */ int osmo_stat_item_discard_all(int32_t *idx) { int discarded = global_value_id + 1 - *idx; @@ -188,7 +239,8 @@ int osmo_stat_item_discard_all(int32_t *idx) return discarded; } -/*! Initialize the stat item module */ +/*! 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; @@ -196,7 +248,10 @@ int osmo_stat_item_init(void *tall_ctx) return 0; } -/*! Search for item group based on group name and index */ +/*! 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) { @@ -213,7 +268,10 @@ struct osmo_stat_item_group *osmo_stat_item_get_group_by_name_idx( return NULL; } -/*! Search for item group based on group name */ +/*! 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) { @@ -233,6 +291,11 @@ const struct osmo_stat_item *osmo_stat_item_get_by_name( 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) { @@ -249,6 +312,10 @@ int osmo_stat_item_for_each_item(struct osmo_stat_item_group *statg, 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; |