stats.h File Reference

Provides stats aggregation and multiple sinks for collected stats. More...

#include "qev.h"

Go to the source code of this file.

Classes
struct	qev_stats_threshold
	For determining if something should be alerted on. More...

Macros
#define	qev_stats_counter_inc(counter)   qev_stats_counter_add(counter, 1);
	Increments a counter. More...
#define	qev_stats_counter_dec(counter)   qev_stats_counter_add(counter, -1);
	Decrements a counter. More...
#define	qev_stats_time(timer, block)
	Times the execution of the given block of code. More...

Typedefs
typedef gint(*	qev_stats_monitor_fn )(const gint64 val, const struct qev_stats_threshold thresh, GString *msg)
	A custom monitoring function. More...
typedef struct qev_stats_gauge	qev_stats_gauge_t
	A gauge stat.
typedef struct qev_stats_counter	qev_stats_counter_t
	A counter stat.
typedef struct qev_stats_timer	qev_stats_timer_t
	A timer stat.

Functions
qev_stats_gauge_t *	qev_stats_gauge (const gchar *prefix, const gchar *name, const gchar *description)
	Adds a gauge to the stats lineup. More...
qev_stats_gauge_t *	qev_stats_gauge_monitor (const gchar *prefix, const gchar *name, const qev_stats_monitor_fn monitor, const gchar *description)
	Adds a gauge to the stats lineup. More...
void	qev_stats_gauge_set (qev_stats_gauge_t *gauge, gint64 val)
	Set the gauge to the given value. More...
gint64	qev_stats_gauge_get (qev_stats_gauge_t *gauge)
	Get the value of the gauge right now. More...
qev_stats_counter_t *	qev_stats_counter (const gchar *prefix, const gchar *name, const gboolean reset_on_flush, const gchar *description)
	Adds a counter to the stats lineup. More...
qev_stats_counter_t *	qev_stats_counter_monitor (const gchar *prefix, const gchar *name, const gboolean reset_on_flush, const qev_stats_monitor_fn monitor, const gchar *description)
	Adds a counter to the stats lineup. More...
gint64	qev_stats_counter_add (qev_stats_counter_t *counter, const gint64 val)
	Add the given value to the counter. More...
gint64	qev_stats_counter_get (qev_stats_counter_t *counter)
	Get the given value to the counter at this instant. More...
qev_stats_timer_t *	qev_stats_timer (const gchar *prefix, const gchar *name, const gchar *description)
	Adds a timer to the stats lineup. More...
qev_stats_timer_t *	qev_stats_timer_monitor (const gchar *prefix, const gchar *name, const qev_stats_monitor_fn monitor_sum, const qev_stats_monitor_fn monitor_stddev, const qev_stats_monitor_fn monitor_mean, const qev_stats_monitor_fn monitor_max, const qev_stats_monitor_fn monitor_min, const qev_stats_monitor_fn monitor_count, const gchar *description)
	Adds a timer to the stats lineup. More...
void	qev_stats_timer_record (qev_stats_timer_t *timer, const gint64 us)
	Records a time to the timer. More...

Detailed Description

Provides stats aggregation and multiple sinks for collected stats.

Typically, stats will be global variables that are treated as references only. Upon passing the stat to any of the add functions, it will be initialized and prepared for life.

Author

Andrew Stone andre.nosp@m.w@cl.nosp@m.ovar..nosp@m.com

Copyright

2012-2014 Clear Channel Inc.

Macro Definition Documentation

#define qev_stats_counter_dec

(

counter

)

qev_stats_counter_add(counter, -1);

Decrements a counter.

Parameters

counter

A pointer to the counter struct

Returns

The value after decrement

#define qev_stats_counter_inc

(

counter

)

qev_stats_counter_add(counter, 1);

Increments a counter.

Parameters

counter

A pointer to the counter struct

Returns

The value after increment

#define qev_stats_time	(		timer,
			block
	)

Value:

{ \
        gint64 qev_stats_timer_start = g_get_monotonic_time(); \
        block; \
	qev_stats_timer_record(timer, g_get_monotonic_time() - qev_stats_timer_start); }

Times the execution of the given block of code.

Parameters

timer	A pointer to the timer
block	The block to time

Typedef Documentation

typedef gint(* qev_stats_monitor_fn)(const gint64 val, const struct qev_stats_threshold thresh, GString *msg)

A custom monitoring function.

Returns a value (typically 0 - 3) indicating how everything is going, typically based off of values in thresh.

Parameters

val	The value of the stat
thresh	The array of thresholds configured
thrs	The number of thresholds
msg[out]	Message to be included with the return value; print your status message into the given GString.

Returns

By convention, returns take one of the following values, but it's acceptable to return different values if your sink knows what to do with them.

0 when OK

1 when WARNING

2 when CRITICAL

3 when UNKNOWN

Function Documentation

qev_stats_counter_t* qev_stats_counter	(	const gchar *	prefix,
		const gchar *	name,
		const gboolean	reset_on_flush,
		const gchar *	description
	)

Adds a counter to the stats lineup.

Parameters

prefix	A prefix for the stat to have
name	The name of the stat (may be A-Za-z0-9._-, . being the path separator)
reset_on_flush	If the counter should be reset between stats flushes
description	What this counter actually measures.

Returns

The stat, useful for qev_stats_counter_inc/dec() and qev_stats_counter_get()

gint64 qev_stats_counter_add	(	qev_stats_counter_t *	counter,
		const gint64	val
	)

Add the given value to the counter.

Parameters

counter	The counter to add the value to
val	The value to add, be it positive or negative.

Returns

The value of the counter after the operation

gint64 qev_stats_counter_get

(

qev_stats_counter_t *

counter

)

Get the given value to the counter at this instant.

Parameters

counter

The counter to add the value to

Returns

The value of the counter right now

qev_stats_counter_t* qev_stats_counter_monitor	(	const gchar *	prefix,
		const gchar *	name,
		const gboolean	reset_on_flush,
		const qev_stats_monitor_fn	monitor,
		const gchar *	description
	)

Adds a counter to the stats lineup.

Parameters

prefix	A prefix for the stat to have
name	The name of the stat (may be A-Za-z0-9._-, . being the path separator)
reset_on_flush	If the counter should be reset between stats flushes
monitor	A custom monitor function (NULL for default monitor)
description	What this counter actually measures.

Returns

The stat, useful for qev_stats_counter_inc/dec() and qev_stats_counter_get()

qev_stats_gauge_t* qev_stats_gauge	(	const gchar *	prefix,
		const gchar *	name,
		const gchar *	description
	)

Adds a gauge to the stats lineup.

Parameters

prefix	A prefix for the stat to have
name	The name of the stat (may be A-Za-z0-9._-, . being the path separator)
description	What this gauge actually measures.

Returns

The stat, useful for qev_stats_gauge_set/get()

gint64 qev_stats_gauge_get

(

qev_stats_gauge_t *

gauge

)

Get the value of the gauge right now.

Parameters

gauge

The gauge to set

Returns

The value of the gauge

qev_stats_gauge_t* qev_stats_gauge_monitor	(	const gchar *	prefix,
		const gchar *	name,
		const qev_stats_monitor_fn	monitor,
		const gchar *	description
	)

Adds a gauge to the stats lineup.

Parameters

prefix	A prefix for the stat to have
name	The name of the stat (may be A-Za-z0-9._-, . being the path separator)
monitor	A custom monitor function (NULL for default monitor)
description	What this gauge actually measures.

Returns

The stat, useful for qev_stats_gauge_set/get()

void qev_stats_gauge_set	(	qev_stats_gauge_t *	gauge,
		gint64	val
	)

Set the gauge to the given value.

Parameters

gauge	The gauge to set
val	The value to set to

qev_stats_timer_t* qev_stats_timer	(	const gchar *	prefix,
		const gchar *	name,
		const gchar *	description
	)

Adds a timer to the stats lineup.

Parameters

prefix	A prefix for the stat to have
name	The name of the stat (may be A-Za-z0-9._-, . being the path separator)
description	What this timer actually times.

Returns

The timer, used for qev_stats_record_time()

qev_stats_timer_t* qev_stats_timer_monitor	(	const gchar *	prefix,
		const gchar *	name,
		const qev_stats_monitor_fn	monitor_sum,
		const qev_stats_monitor_fn	monitor_stddev,
		const qev_stats_monitor_fn	monitor_mean,
		const qev_stats_monitor_fn	monitor_max,
		const qev_stats_monitor_fn	monitor_min,
		const qev_stats_monitor_fn	monitor_count,
		const gchar *	description
	)

Adds a timer to the stats lineup.

Parameters

prefix	A prefix for the stat to have
name	The name of the stat (may be A-Za-z0-9._-, . being the path separator)
monitor_sum	Custom monitor for the timer's sum value (NULL for default monitor)
monitor_stddev	Custom monitor for the timer's standard deviation value (NULL for default monitor)
monitor_mean	Custom monitor for the timer's mean value (NULL for default monitor)
monitor_max	Custom monitor for the timer's max value (NULL for default monitor)
monitor_min	Custom monitor for the timer's min value (NULL for default monitor)
monitor_count	Custom monitor for the timer's count (NULL for default monitor)
description	What this timer actually times.

Returns

The timer, used for qev_stats_record_time()

void qev_stats_timer_record	(	qev_stats_timer_t *	timer,
		const gint64	us
	)

Records a time to the timer.

Parameters

timer	The timer struct
us	Microseconds to record