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

Files
file	stat_item.h

Data Structures
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...

struct	osmo_stat_item_period

struct	osmo_stat_item
	data we keep for each actual item 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_group *	osmo_stat_item_group_alloc (void ctx, const struct osmo_stat_item_group_desc group_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)

struct osmo_stat_item *	osmo_stat_item_group_get_item (struct osmo_stat_item_group *grp, unsigned int idx)
	Get statistics item from group, identified by index idx. More...

void	osmo_stat_item_group_set_name (struct osmo_stat_item_group statg, const char name)
	Set a name for the statistics item group to be used instead of index value at report time. More...

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_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. More...

struct osmo_stat_item_group *	osmo_stat_item_get_group_by_name_idxname (const char group_name, const char idx_name)
	Search for item group based on group name and index's name. More...

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

int32_t	osmo_stat_item_get_last (const struct osmo_stat_item *item)
	Get the last (freshest) value. More...

void	osmo_stat_item_flush (struct osmo_stat_item *item)
	Indicate that a reporting period has elapsed, and prepare the stat item for a new period of collecting min/max/avg. 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...

const struct osmo_stat_item_desc *	osmo_stat_item_get_desc (struct osmo_stat_item *item)
	Return the description for an osmo_stat_item. More...

static	LLIST_HEAD (osmo_stat_item_groups)
	global list of stat_item groups More...

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

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]	item	The stat_item whose value we want to set
[in]	value	The numeric value we want to store at end of FIFO

References osmo_stat_item_period::last, osmo_stat_item_set(), and value.

◆ osmo_stat_item_flush()

void osmo_stat_item_flush ( struct osmo_stat_item * item )

Indicate that a reporting period has elapsed, and prepare the stat item for a new period of collecting min/max/avg.

Parameters

item	Stat item to flush.

References osmo_stat_item_period::last, osmo_stat_item_period::max, osmo_stat_item_period::min, osmo_stat_item_period::n, reported, osmo_stat_item_period::sum, and value.

Referenced by osmo_stat_item_handler().

◆ 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_group	Call-back function, aborts if rc < 0
[in]	data	Private 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]	statg	stat_item group over whose items to iterate
[in]	handle_item	Call-back function, aborts if rc < 0
[in]	data	Private 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]	statg	group in which to search for the item
[in]	name	name 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_desc()

const struct osmo_stat_item_desc * osmo_stat_item_get_desc ( struct osmo_stat_item * item )

Return the description for an osmo_stat_item.

References desc.

◆ 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]	name	Name of stats_item_group we want to find
[in]	idx	Index 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_group_by_name_idxname()

struct osmo_stat_item_group * osmo_stat_item_get_group_by_name_idxname	(	const char *	group_name,
		const char *	idx_name
	)

Search for item group based on group name and index's name.

Parameters

[in]	name	Name of stats_item_group we want to find.
[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.

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

◆ osmo_stat_item_get_last()

int32_t osmo_stat_item_get_last ( const struct osmo_stat_item * item )

Get the last (freshest) value.

References osmo_stat_item_period::last, and value.

◆ osmo_stat_item_group_alloc()

struct osmo_stat_item_group * osmo_stat_item_group_alloc	(	void *	ctx,
		const struct osmo_stat_item_group_desc *	group_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]	ctx	talloc context
[in]	desc	Statistics item group description
[in]	idx	Index of new stat item group

References osmo_stat_item_desc::default_value, osmo_stat_item_group::desc, desc, osmo_stat_item_group::idx, osmo_stat_item_group_desc::item_desc, osmo_stat_item_group::items, osmo_stat_item_group::list, llist_add(), osmo_stat_item_group_desc::num_items, OSMO_ASSERT, and tall_stat_item_ctx.

Referenced by fill_stats().

◆ 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().

Referenced by osmo_stats_tcp_osmo_fd_unregister().

◆ osmo_stat_item_group_get_item()

struct osmo_stat_item * osmo_stat_item_group_get_item	(	struct osmo_stat_item_group *	grp,
		unsigned int	idx
	)

Get statistics item from group, identified by index idx.

Parameters

[in]	grp	Rate counter group
[in]	idx	Index of the counter to retrieve

Returns: rate counter requested

References osmo_stat_item_group::items.

Referenced by fill_stats().

◆ 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] statg stat 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_set_name()

void osmo_stat_item_group_set_name	(	struct osmo_stat_item_group *	statg,
		const char *	name
	)

Set a name for the statistics item group to be used instead of index value at report time.

Parameters

[in]	statg	Statistics item group
[in]	name	Name identifier to assign to the statistics item group

References name, osmo_stat_item_group::name, and osmo_talloc_replace_string().

Referenced by fill_stats().

◆ osmo_stat_item_group_udp_idx()

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

inlinestatic

References osmo_stat_item_group::idx.

◆ 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]	item	The stat_item whose value we want to set
[in]	value	The numeric value we want to store at end of FIFO

References osmo_stat_item_period::last, osmo_stat_item_set(), and value.

◆ 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_ctx Talloc 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 )

Remove all values of a stat item.

Parameters

[in] item stat item to reset

References osmo_stat_item_desc::default_value, desc, osmo_stat_item_period::last, osmo_stat_item_period::max, osmo_stat_item_period::min, osmo_stat_item_period::n, osmo_stat_item_period::sum, and value.

Referenced by osmo_stat_item_group_reset().

◆ 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]	item	The stat_item whose value we want to set
[in]	value	The numeric value we want to store at end of FIFO

References osmo_stat_item_period::last, osmo_stat_item_period::max, osmo_stat_item_period::min, osmo_stat_item_period::n, OSMO_MAX, OSMO_MIN, osmo_stat_item_period::sum, and value.

Referenced by fill_stats(), osmo_stat_item_dec(), and osmo_stat_item_inc().

Variable Documentation

◆ 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().

Files

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ OSMO_STAT_ITEM_NO_UNIT

◆ OSMO_STAT_ITEM_NOVALUE_ID

Typedef Documentation

◆ osmo_stat_item_group_handler_t

◆ osmo_stat_item_handler_t

Function Documentation

◆ LLIST_HEAD()

◆ osmo_stat_item_dec()

◆ osmo_stat_item_flush()

◆ osmo_stat_item_for_each_group()

◆ osmo_stat_item_for_each_item()

◆ osmo_stat_item_get_by_name()

◆ osmo_stat_item_get_desc()

◆ osmo_stat_item_get_group_by_name_idx()

◆ osmo_stat_item_get_group_by_name_idxname()

◆ osmo_stat_item_get_last()

◆ osmo_stat_item_group_alloc()

◆ osmo_stat_item_group_free()

◆ osmo_stat_item_group_get_item()

◆ osmo_stat_item_group_reset()

◆ osmo_stat_item_group_set_name()

◆ osmo_stat_item_group_udp_idx()

◆ osmo_stat_item_inc()

◆ osmo_stat_item_init()

◆ osmo_stat_item_reset()

◆ osmo_stat_item_set()

Variable Documentation

◆ tall_stat_item_ctx