libosmocore  1.5.1
Osmocom core library
Statistics value item

Files

file  stat_item.h
 

Data Structures

struct  osmo_stat_item_value
 Individual entry in value FIFO. More...
 
struct  osmo_stat_item
 data we keep for each actual item More...
 
struct  osmo_stat_item_desc
 Statistics item description. More...
 
struct  osmo_stat_item_group_desc
 Description of a statistics item group. More...
 
struct  osmo_stat_item_group
 One instance of a counter group class. More...
 

Macros

#define OSMO_STAT_ITEM_NOVALUE_ID   0
 
#define OSMO_STAT_ITEM_NO_UNIT   NULL
 

Typedefs

typedef int(* osmo_stat_item_handler_t) (struct osmo_stat_item_group *, struct osmo_stat_item *, void *)
 
typedef int(* osmo_stat_item_group_handler_t) (struct osmo_stat_item_group *, void *)
 

Functions

struct osmo_stat_item_grouposmo_stat_item_group_alloc (void *ctx, const struct osmo_stat_item_group_desc *desc, unsigned int idx)
 Allocate a new group of counters according to description. More...
 
static void osmo_stat_item_group_udp_idx (struct osmo_stat_item_group *grp, unsigned int idx)
 
void osmo_stat_item_group_free (struct osmo_stat_item_group *grp)
 Free the memory for the specified group of stat items. More...
 
void osmo_stat_item_inc (struct osmo_stat_item *item, int32_t value)
 Increase the stat_item to the given value. More...
 
void osmo_stat_item_dec (struct osmo_stat_item *item, int32_t value)
 Descrease the stat_item to the given value. More...
 
void osmo_stat_item_set (struct osmo_stat_item *item, int32_t value)
 Set the a given stat_item to the given value. More...
 
int osmo_stat_item_init (void *tall_ctx)
 Initialize the stat item module. More...
 
struct osmo_stat_item_grouposmo_stat_item_get_group_by_name_idx (const char *name, const unsigned int idx)
 Search for item group based on group name and index. More...
 
const struct osmo_stat_itemosmo_stat_item_get_by_name (const struct osmo_stat_item_group *statg, const char *name)
 Search for item based on group + item name. More...
 
int osmo_stat_item_get_next (const struct osmo_stat_item *item, int32_t *next_idx, int32_t *value)
 Retrieve the next value from the osmo_stat_item object. More...
 
static int32_t osmo_stat_item_get_last (const struct osmo_stat_item *item)
 Get the last (freshest) value. More...
 
int osmo_stat_item_discard (const struct osmo_stat_item *item, int32_t *idx)
 Skip/discard all values of this item and update idx accordingly. More...
 
int osmo_stat_item_discard_all (int32_t *idx)
 Skip all values of all items and update idx accordingly. More...
 
int osmo_stat_item_for_each_item (struct osmo_stat_item_group *statg, osmo_stat_item_handler_t handle_item, void *data)
 Iterate over all items in group, call user-supplied function on each. More...
 
int osmo_stat_item_for_each_group (osmo_stat_item_group_handler_t handle_group, void *data)
 Iterate over all stat_item groups in system, call user-supplied function on each. More...
 
void osmo_stat_item_reset (struct osmo_stat_item *item)
 Remove all values of a stat item. More...
 
void osmo_stat_item_group_reset (struct osmo_stat_item_group *statg)
 Reset all osmo stat items in a group. More...
 
static LLIST_HEAD (osmo_stat_item_groups)
 global list of stat_item groups More...
 

Variables

static int32_t global_value_id = 0
 counter for assigning globally unique value identifiers More...
 
static void * tall_stat_item_ctx
 talloc context from which we allocate More...
 

Detailed Description

This osmo_stat_item module adds instrumentation capabilities to gather measurement and statistical values in a similar fashion to what we have as 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.

Macro Definition Documentation

◆ OSMO_STAT_ITEM_NO_UNIT

#define OSMO_STAT_ITEM_NO_UNIT   NULL

◆ OSMO_STAT_ITEM_NOVALUE_ID

#define OSMO_STAT_ITEM_NOVALUE_ID   0

Typedef Documentation

◆ osmo_stat_item_group_handler_t

typedef int(* osmo_stat_item_group_handler_t) (struct osmo_stat_item_group *, void *)

◆ osmo_stat_item_handler_t

typedef int(* osmo_stat_item_handler_t) (struct osmo_stat_item_group *, struct osmo_stat_item *, void *)

Function Documentation

◆ LLIST_HEAD()

static LLIST_HEAD ( osmo_stat_item_groups  )
static

global list of stat_item groups

◆ osmo_stat_item_dec()

void osmo_stat_item_dec ( struct osmo_stat_item item,
int32_t  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.

Parameters
[in]itemThe stat_item whose value we want to set
[in]valueThe numeric value we want to store at end of FIFO

References last_offs, osmo_stat_item_set(), osmo_stat_item_value::value, and values.

◆ osmo_stat_item_discard()

int osmo_stat_item_discard ( const struct osmo_stat_item item,
int32_t *  idx 
)

Skip/discard all values of this item and update idx accordingly.

References osmo_stat_item_value::id, last_offs, and values.

◆ osmo_stat_item_discard_all()

int osmo_stat_item_discard_all ( int32_t *  idx)

Skip all values of all items and update idx accordingly.

References global_value_id.

Referenced by osmo_stats_init(), and osmo_stats_report().

◆ osmo_stat_item_for_each_group()

int osmo_stat_item_for_each_group ( osmo_stat_item_group_handler_t  handle_group,
void *  data 
)

Iterate over all stat_item groups in system, call user-supplied function on each.

Parameters
[in]handle_groupCall-back function, aborts if rc < 0
[in]dataPrivate data handed through to handle_group

References data, list, and llist_for_each_entry.

Referenced by osmo_stats_report().

◆ osmo_stat_item_for_each_item()

int osmo_stat_item_for_each_item ( struct osmo_stat_item_group statg,
osmo_stat_item_handler_t  handle_item,
void *  data 
)

Iterate over all items in group, call user-supplied function on each.

Parameters
[in]statgstat_item group over whose items to iterate
[in]handle_itemCall-back function, aborts if rc < 0
[in]dataPrivate data handed through to handle_item

References data, osmo_stat_item_group::desc, osmo_stat_item_group::items, and osmo_stat_item_group_desc::num_items.

Referenced by osmo_stat_item_group_handler().

◆ osmo_stat_item_get_by_name()

const struct osmo_stat_item * osmo_stat_item_get_by_name ( const struct osmo_stat_item_group statg,
const char *  name 
)

Search for item based on group + item name.

Parameters
[in]statggroup in which to search for the item
[in]namename of item to search within statg
Returns
pointer to item, if found; NULL otherwise

References osmo_stat_item_group::desc, osmo_stat_item_group_desc::item_desc, osmo_stat_item_group::items, name, osmo_stat_item_desc::name, and osmo_stat_item_group_desc::num_items.

◆ osmo_stat_item_get_group_by_name_idx()

struct osmo_stat_item_group * osmo_stat_item_get_group_by_name_idx ( const char *  name,
const unsigned int  idx 
)

Search for item group based on group name and index.

Parameters
[in]nameName of stats_item_group we want to find
[in]idxIndex of the group we want to find
Returns
pointer to group, if found; NULL otherwise

References osmo_stat_item_group::desc, osmo_stat_item_group_desc::group_name_prefix, osmo_stat_item_group::idx, list, llist_for_each_entry, and name.

◆ osmo_stat_item_get_last()

static int32_t osmo_stat_item_get_last ( const struct osmo_stat_item item)
inlinestatic

Get the last (freshest) value.

References last_offs, osmo_stat_item_value::value, and values.

Referenced by osmo_stat_item_handler().

◆ osmo_stat_item_get_next()

int osmo_stat_item_get_next ( const struct osmo_stat_item item,
int32_t *  next_idx,
int32_t *  value 
)

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.

Parameters
valthe osmo_stat_item object
idxidentifies the next value to be read
valuea 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)

References desc, osmo_stat_item_value::id, last_offs, osmo_stat_item_desc::num_values, OSMO_STAT_ITEM_NOVALUE_ID, osmo_stat_item_value::value, and values.

Referenced by osmo_stat_item_handler().

◆ osmo_stat_item_group_alloc()

struct osmo_stat_item_group * osmo_stat_item_group_alloc ( void *  ctx,
const struct osmo_stat_item_group_desc desc,
unsigned int  idx 
)

Allocate a new group of counters according to description.

Allocate a group of stat items described in desc from talloc context ctx, giving the new group the index idx.

Parameters
[in]ctxtalloc context
[in]descStatistics item group description
[in]idxIndex of new stat item group

References desc, osmo_stat_item_group::desc, osmo_stat_item_value::id, osmo_stat_item_group::idx, osmo_stat_item_group::items, last_offs, last_value_index, osmo_stat_item_group::list, llist_add(), OSMO_STAT_ITEM_NOVALUE_ID, tall_stat_item_ctx, osmo_stat_item_value::value, and values.

◆ osmo_stat_item_group_free()

void osmo_stat_item_group_free ( struct osmo_stat_item_group statg)

Free the memory for the specified group of stat items.

References osmo_stat_item_group::list, and llist_del().

◆ osmo_stat_item_group_reset()

void osmo_stat_item_group_reset ( struct osmo_stat_item_group statg)

Reset all osmo stat items in a group.

Parameters
[in]statgstat item group to reset

References osmo_stat_item_group::desc, osmo_stat_item_group::items, osmo_stat_item_group_desc::num_items, and osmo_stat_item_reset().

◆ osmo_stat_item_group_udp_idx()

static void osmo_stat_item_group_udp_idx ( struct osmo_stat_item_group grp,
unsigned int  idx 
)
inlinestatic

◆ osmo_stat_item_inc()

void osmo_stat_item_inc ( struct osmo_stat_item item,
int32_t  value 
)

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.

Parameters
[in]itemThe stat_item whose value we want to set
[in]valueThe numeric value we want to store at end of FIFO

References last_offs, osmo_stat_item_set(), osmo_stat_item_value::value, and values.

◆ osmo_stat_item_init()

int osmo_stat_item_init ( void *  tall_ctx)

Initialize the stat item module.

Call this once from your program.

Parameters
[in]tall_ctxTalloc context from which this module allocates

References tall_stat_item_ctx.

◆ osmo_stat_item_reset()

void osmo_stat_item_reset ( struct osmo_stat_item item)

◆ osmo_stat_item_set()

void osmo_stat_item_set ( struct osmo_stat_item item,
int32_t  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.

Parameters
[in]itemThe stat_item whose value we want to set
[in]valueThe numeric value we want to store at end of FIFO

References desc, global_value_id, osmo_stat_item_value::id, last_offs, osmo_stat_item_desc::num_values, OSMO_STAT_ITEM_NOVALUE_ID, osmo_stat_item_value::value, and values.

Referenced by osmo_stat_item_dec(), and osmo_stat_item_inc().

Variable Documentation

◆ global_value_id

int32_t global_value_id = 0
static

counter for assigning globally unique value identifiers

Referenced by osmo_stat_item_discard_all(), and osmo_stat_item_set().

◆ tall_stat_item_ctx

void* tall_stat_item_ctx
static

talloc context from which we allocate

Referenced by osmo_stat_item_group_alloc(), and osmo_stat_item_init().