libosmocore 1.13.1.1-afb4 Osmocom core library

Files | Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
Rate counters

Counters about events and their event rates. More...

## Files
file | rate_ctr.h
file | rate_ctr.c

## Data Structures
struct | rate_ctr_per_intv
| data we keep for each of the intervals More...
struct | rate_ctr
| data we keep for each actual value More...
struct | rate_ctr_desc
| rate counter description More...
struct | rate_ctr_group_desc
| description of a rate counter group More...
struct | rate_ctr_group
| One instance of a counter group class. More...

## Macros
#define | RATE_CTR_INTV_NUM 4
| Number of rate counter intervals. More...

## Typedefs
typedef int(* | rate_ctr_handler_t) (struct rate_ctr_group *, struct rate_ctr *, const struct rate_ctr_desc *, void *)
typedef int(* | rate_ctr_group_handler_t) (struct rate_ctr_group *, void *)

## Enumerations
enum | rate_ctr_intv { RATE_CTR_INTV_SEC , RATE_CTR_INTV_MIN , RATE_CTR_INTV_HOUR , RATE_CTR_INTV_DAY }
| Rate counter interval. More...

## Functions
static int | rate_ctr_handler (struct rate_ctr_group *ctrg, struct rate_ctr *ctr, const struct rate_ctr_desc *desc, void *vctx_)
void | vty_out_rate_ctr_group2 (struct vty *vty, const char *prefix, struct rate_ctr_group *ctrg, bool skip_zero)
void | vty_out_rate_ctr_group (struct vty *vty, const char *prefix, struct rate_ctr_group *ctrg)
static char * | pad_append_str (char *s, const char *a, int minwidth)
static char * | pad_append_ctr (char *s, uint64_t ctr, int minwidth)
static int | rate_ctr_handler_fmt (struct rate_ctr_group *ctrg, struct rate_ctr *ctr, const struct rate_ctr_desc *desc, void *vctx_)
void | vty_out_rate_ctr_group_fmt2 (struct vty *vty, const char *fmt, struct rate_ctr_group *ctrg, bool skip_zero)
void | vty_out_rate_ctr_group_fmt (struct vty *vty, const char *fmt, struct rate_ctr_group *ctrg)
static int | rate_ctr_group_handler (struct rate_ctr_group *ctrg, void *vctx_)
struct rate_ctr_group * | rate_ctr_group_alloc (void *ctx, const struct rate_ctr_group_desc *desc, unsigned int idx)
| Allocate a new group of counters according to description. More...
static void | rate_ctr_group_upd_idx (struct rate_ctr_group *grp, unsigned int idx)
void | rate_ctr_group_set_name (struct rate_ctr_group *grp, const char *name)
| Set a name for the group of counters be used instead of index value at report time. More...
struct rate_ctr * | rate_ctr_group_get_ctr (struct rate_ctr_group *grp, unsigned int idx)
| Get rate counter from group, identified by index idx. More...
void | rate_ctr_group_free (struct rate_ctr_group *grp)
| Free the memory for the specified group of counters. More...
void | rate_ctr_add (struct rate_ctr *ctr, int inc)
| Increment the counter by inc. More...
static void | rate_ctr_add2 (struct rate_ctr_group *ctrg, unsigned int idx, int inc)
| Increment the counter by inc. More...
static void | rate_ctr_inc (struct rate_ctr *ctr)
| Increment the counter by 1. More...
static void | rate_ctr_inc2 (struct rate_ctr_group *ctrg, unsigned int idx)
| Increment the counter by 1. More...
int64_t | rate_ctr_difference (struct rate_ctr *ctr)
| Return the counter difference since the last call to this function. More...
int | rate_ctr_init (void *tall_ctx)
| Initialize the counter module. More...
struct rate_ctr_group * | rate_ctr_get_group_by_name_idx (const char *name, const unsigned int idx)
| Search for counter group based on group name and index. More...
const struct rate_ctr * | rate_ctr_get_by_name (const struct rate_ctr_group *ctrg, const char *name)
| Search for counter based on group + name. More...
int | rate_ctr_for_each_counter (struct rate_ctr_group *ctrg, rate_ctr_handler_t handle_counter, void *data)
| Iterate over each counter in group and call function. More...
int | rate_ctr_for_each_group (rate_ctr_group_handler_t handle_group, void *data)
| Iterate over all counter groups. More...
void | rate_ctr_reset (struct rate_ctr *ctr)
| Reset a rate counter back to zero. More...
void | rate_ctr_group_reset (struct rate_ctr_group *ctrg)
| Reset all counters in a group. More...
static | LLIST_HEAD (rate_ctr_groups)
static bool | rate_ctrl_group_desc_validate (const struct rate_ctr_group_desc *desc)
static char * | mangle_identifier_ifneeded (const void *ctx, const char *in)
static struct rate_ctr_group_desc * | rate_ctr_group_desc_mangle (void *ctx, const struct rate_ctr_group_desc *desc)
static unsigned int | rate_ctr_get_unused_name_idx (const char *name)
| Find an unused index for this rate counter group. More...
static void | interval_expired (struct rate_ctr *ctr, enum rate_ctr_intv intv)
static void | rate_ctr_group_intv (struct rate_ctr_group *grp)
static int | rate_ctr_timer_cb (struct osmo_fd *ofd, unsigned int what)

## Variables
static void * | tall_rate_ctr_ctx
static struct osmo_fd | rate_ctr_timer = { .fd = -1 }
static uint64_t | timer_ticks

## Detailed Description

Counters about events and their event rates.

As osmo_counter and Statistics value item are concerned only with a single given value that may be increased/decreased, or the difference to one given previous value, this module adds some support for keeping long term information about a given event rate.

A Rate counters keeps information on the amount of events per second, per minute, per hour and per day.

Rate counters come in groups: An application describes a group of counters with their names and identities once in a (typically const) rate_ctr_group_desc.

As objects (such as e.g. a subscriber or a PDP context) are allocated dynamically at runtime, the application calls rate_ctr_group_alloc with a refernce to the rate_ctr_group_desc, which causes the library to allocate one set of rate_ctr: One for each in the group.

The application then uses functions like rate_ctr_add or rate_ctr_inc to increment the value as certain events (e.g. location update) happens.

The library internally keeps a timer once per second which iterates over all registered counters and which updates the per-second, per-minute, per-hour and per-day averages based on the current value.

The counters can be reported using Statistics reporting or by VTY introspection, as well as by any application-specific code accessing the rate_ctr::intv array directly.

## Macro Definition Documentation

## ◆ RATE_CTR_INTV_NUM

#define RATE_CTR_INTV_NUM 4

Number of rate counter intervals.

## Typedef Documentation

## ◆ rate_ctr_group_handler_t

typedef int(* rate_ctr_group_handler_t) (struct rate_ctr_group *, void *)

## ◆ rate_ctr_handler_t

typedef int(* rate_ctr_handler_t) (struct rate_ctr_group *, struct rate_ctr *, const struct rate_ctr_desc *, void *)

## Enumeration Type Documentation

## ◆ rate_ctr_intv

enum rate_ctr_intv

Rate counter interval.

Enumerator
RATE_CTR_INTV_SEC | last second
RATE_CTR_INTV_MIN | last minute
RATE_CTR_INTV_HOUR | last hour
RATE_CTR_INTV_DAY | last day

## Function Documentation

## ◆ interval_expired()

static void interval_expired | ( | struct rate_ctr * | ctr,
|  | enum rate_ctr_intv | intv
| ) |  |
| static

References current, intv, rate_ctr_per_intv::last, and rate_ctr_per_intv::rate.

Referenced by rate_ctr_group_intv().

## ◆ LLIST_HEAD()

static LLIST_HEAD | ( | rate_ctr_groups |  | ) |
| static

## ◆ mangle_identifier_ifneeded()

static char * mangle_identifier_ifneeded | ( | const void * | ctx,
|  | const char * | in
| ) |  |
| static

References DLGLOBAL, LOGL_NOTICE, LOGP, and OSMO_ASSERT.

Referenced by rate_ctr_group_desc_mangle().

## ◆ rate_ctr_add()

void rate_ctr_add | ( | struct rate_ctr * | ctr,
|  | int | inc
| ) |  |

Increment the counter by inc.

Add a number to the counter.

Parameters

  ctr | Rate counters to increment
  inc | quantity to increment ctr by

References current.

Referenced by rate_ctr_add2(), and rate_ctr_inc().

## ◆ rate_ctr_add2()

static void rate_ctr_add2 | ( | struct rate_ctr_group * | ctrg,
|  | unsigned int | idx,
|  | int | inc
| ) |  |
| inline static

Increment the counter by inc.

Parameters

  ctrg | rate_ctr_group of counter
  idx | index into ctrg counter group
  inc | quantity to increment ctr by

References rate_ctr_add(), and rate_ctr_group_get_ctr().

## ◆ rate_ctr_difference()

int64_t rate_ctr_difference | ( | struct rate_ctr * | ctr | ) |

Return the counter difference since the last call to this function.

References current, and previous.

Referenced by rate_ctr_handler().

## ◆ rate_ctr_for_each_counter()

int rate_ctr_for_each_counter | ( | struct rate_ctr_group * | ctrg,
|  | rate_ctr_handler_t | handle_counter,
|  | void * | data
| ) |  |

Iterate over each counter in group and call function.

Parameters

  [in] | ctrg | counter group over which to iterate
  [in] | handle_counter | function pointer
  [in] | data | Data to hand transparently to handle_counter()

Returns
  0 on success; negative otherwise

References rate_ctr_group::ctr, rate_ctr_group_desc::ctr_desc, data, rate_ctr_group::desc, handle_counter(), and rate_ctr_group_desc::num_ctr.

Referenced by rate_ctr_group_handler().

## ◆ rate_ctr_for_each_group()

int rate_ctr_for_each_group | ( | rate_ctr_group_handler_t | handle_group,
|  | void * | data
| ) |  |

Iterate over all counter groups.

Parameters

  [in] | handle_group | function pointer of callback function
  [in] | data | Data to hand transparently to handle_group()

Returns
  0 on success; negative otherwise

References data, list, and llist_for_each_entry.

Referenced by osmo_stats_report().

## ◆ rate_ctr_get_by_name()

const struct rate_ctr * rate_ctr_get_by_name | ( | const struct rate_ctr_group * | ctrg,
|  | const char * | name
| ) |  |

Search for counter based on group + name.

Parameters

  [in] | ctrg | pointer to rate_ctr_group
  [in] | name | name of counter inside group

Returns
  Rate counters or NULL in case of error

References rate_ctr_group::ctr, rate_ctr_group_desc::ctr_desc, rate_ctr_group::desc, name, rate_ctr_desc::name, and rate_ctr_group_desc::num_ctr.

## ◆ rate_ctr_get_group_by_name_idx()

struct rate_ctr_group * rate_ctr_get_group_by_name_idx | ( | const char * | name,
|  | const unsigned int | idx
| ) |  |

Search for counter group based on group name and index.

Parameters

  [in] | name | Name of the counter group you're looking for
  [in] | idx | Index inside the counter group

Returns
  rate_ctr_group or NULL in case of error

References rate_ctr_group::desc, rate_ctr_group_desc::group_name_prefix, rate_ctr_group::idx, list, llist_for_each_entry, and name.

Referenced by rate_ctr_group_alloc().

## ◆ rate_ctr_get_unused_name_idx()

static unsigned int rate_ctr_get_unused_name_idx | ( | const char * | name | ) |
| static

Find an unused index for this rate counter group.

Parameters

  [in] | name | Name of the counter group

Returns
  the largest used index number + 1, or 0 if none exist yet.

References rate_ctr_group::desc, rate_ctr_group_desc::group_name_prefix, rate_ctr_group::idx, list, llist_for_each_entry, and name.

Referenced by rate_ctr_group_alloc().

## ◆ rate_ctr_group_alloc()

struct rate_ctr_group * rate_ctr_group_alloc | ( | void * | ctx,
|  | const struct rate_ctr_group_desc * | desc,
|  | unsigned int | idx
| ) |  |

Allocate a new group of counters according to description.

Parameters

  [in] | ctx | parent talloc context
  [in] | desc | Rate counter group description
  [in] | idx | Index of new counter group

References rate_ctr_group::desc, DLGLOBAL, rate_ctr_group::idx, rate_ctr_group::list, llist_add(), LOGL_ERROR, LOGP, rate_ctr_get_group_by_name_idx(), rate_ctr_get_unused_name_idx(), rate_ctr_group_desc_mangle(), rate_ctrl_group_desc_validate(), and tall_rate_ctr_ctx.

## ◆ rate_ctr_group_desc_mangle()

static struct rate_ctr_group_desc * rate_ctr_group_desc_mangle | ( | void * | ctx,
|  | const struct rate_ctr_group_desc * | desc
| ) |  |
| static

References rate_ctr_group_desc::class_id, rate_ctr_group_desc::ctr_desc, rate_ctr_desc::description, DLGLOBAL, rate_ctr_group_desc::group_description, rate_ctr_group_desc::group_name_prefix, if(), LOGL_ERROR, LOGL_INFO, LOGP, mangle_identifier_ifneeded(), name, rate_ctr_desc::name, rate_ctr_group_desc::num_ctr, OSMO_ASSERT, and rate_ctrl_group_desc_validate().

Referenced by rate_ctr_group_alloc().

## ◆ rate_ctr_group_free()

void rate_ctr_group_free | ( | struct rate_ctr_group * | grp | ) |

Free the memory for the specified group of counters.

References rate_ctr_group::list, llist_del(), and llist_empty().

## ◆ rate_ctr_group_get_ctr()

struct rate_ctr * rate_ctr_group_get_ctr | ( | struct rate_ctr_group * | grp,
|  | unsigned int | idx
| ) |  |

Get rate counter 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 rate_ctr_group::ctr.

Referenced by rate_ctr_add2(), and rate_ctr_inc2().

## ◆ rate_ctr_group_intv()

static void rate_ctr_group_intv | ( | struct rate_ctr_group * | grp | ) |
| static

References rate_ctr_group::ctr, rate_ctr_group::desc, interval_expired(), rate_ctr_group_desc::num_ctr, RATE_CTR_INTV_DAY, RATE_CTR_INTV_HOUR, RATE_CTR_INTV_MIN, RATE_CTR_INTV_SEC, and timer_ticks.

Referenced by rate_ctr_timer_cb().

## ◆ rate_ctr_group_reset()

void rate_ctr_group_reset | ( | struct rate_ctr_group * | ctrg | ) |

Reset all counters in a group.

Parameters

  [in] | ctrg | counter group to reset

References rate_ctr_group::ctr, rate_ctr_group::desc, rate_ctr_group_desc::num_ctr, and rate_ctr_reset().

## ◆ rate_ctr_group_set_name()

void rate_ctr_group_set_name | ( | struct rate_ctr_group * | grp,
|  | const char * | name
| ) |  |

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

Parameters

  [in] | grp | Rate counter group
  [in] | name | Name identifier to assign to the rate counter group

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

## ◆ rate_ctr_group_upd_idx()

static void rate_ctr_group_upd_idx | ( | struct rate_ctr_group * | grp,
|  | unsigned int | idx
| ) |  |
| inline static

References rate_ctr_group::idx.

## ◆ rate_ctr_inc()

static void rate_ctr_inc | ( | struct rate_ctr * | ctr | ) |
| inline static

Increment the counter by 1.

Parameters

  ctr | Rate counters to increment

References rate_ctr_add().

Referenced by rate_ctr_inc2().

## ◆ rate_ctr_inc2()

static void rate_ctr_inc2 | ( | struct rate_ctr_group * | ctrg,
|  | unsigned int | idx
| ) |  |
| inline static

Increment the counter by 1.

Parameters

  ctrg | rate_ctr_group of counter
  idx | index into ctrg counter group

References rate_ctr_group_get_ctr(), and rate_ctr_inc().

## ◆ rate_ctr_init()

int rate_ctr_init | ( | void * | tall_ctx | ) |

Initialize the counter module.

Call this once from your application.

Parameters

  [in] | tall_ctx | Talloc context from which rate_ctr_group will be allocated

Returns
  0 on success; negative on error

References DLGLOBAL, osmo_fd::fd, LOGL_ERROR, LOGP, osmo_fd_is_registered(), osmo_timerfd_schedule(), osmo_timerfd_setup(), rate_ctr_timer, rate_ctr_timer_cb(), and tall_rate_ctr_ctx.

## ◆ rate_ctr_reset()

void rate_ctr_reset | ( | struct rate_ctr * | ctr | ) |

Reset a rate counter back to zero.

Parameters

  [in] | ctr | counter to reset

References rate_ctr_group::ctr.

Referenced by rate_ctr_group_reset().

## ◆ rate_ctr_timer_cb()

static int rate_ctr_timer_cb | ( | struct osmo_fd * | ofd,
|  | unsigned int | what
| ) |  |
| static

References DLGLOBAL, osmo_fd::fd, list, llist_for_each_entry, LOGL_NOTICE, LOGP, OSMO_ASSERT, OSMO_FD_READ, rate_ctr_group_intv(), and timer_ticks.

Referenced by rate_ctr_init().

## ◆ rate_ctrl_group_desc_validate()

static bool rate_ctrl_group_desc_validate | ( | const struct rate_ctr_group_desc * | desc | ) |
| static

References DEBUGP, DLGLOBAL, LOGL_ERROR, LOGP, name, and osmo_identifier_valid().

Referenced by rate_ctr_group_alloc(), and rate_ctr_group_desc_mangle().

## Variable Documentation

## ◆ rate_ctr_timer

struct osmo_fd rate_ctr_timer = { .fd = -1 }
| static

Referenced by rate_ctr_init().

## ◆ tall_rate_ctr_ctx

void* tall_rate_ctr_ctx
| static

Referenced by rate_ctr_group_alloc(), and rate_ctr_init().

## ◆ timer_ticks

uint64_t timer_ticks
| static

Referenced by rate_ctr_group_intv(), and rate_ctr_timer_cb().