lws-metrics.h File Reference

Go to the source code of this file.

Data Structures
struct	lws_metrics_tag
struct	lws_metric_bucket
struct	lws_metric_pub
struct	lws_metric_caliper
union	lws_metric_pub.u
struct	lws_metric_pub.u.agg
struct	lws_metric_pub.u.hist

Macros
#define	lws_metrics_tag_wsi_add(_a, _b, _c)
#define	lws_metric_bucket_name_len(_b)   (*((uint8_t *)&(_b)[1]))
#define	lws_metric_bucket_name(_b)   (((const char *)&(_b)[1]) + 1)
#define	lws_metrics_caliper_compose(_name)
#define	lws_metrics_caliper_bind(_name, _mt)
#define	lws_metrics_caliper_declare(_name, _mp)
#define	lws_metrics_caliper_report(_name, _go_nogo)
#define	lws_metrics_caliper_report_hist(_name, pwsiconn)
#define	lws_metrics_caliper_cancel(_name)
#define	lws_metrics_hist_bump(_mt, _name)
#define	lws_metrics_hist_bump_priv(_mt, _name)
#define	lws_metrics_caliper_done(_name)
#define	METRES_GO   0
#define	METRES_NOGO   1

Typedefs
typedef uint64_t	u_mt_t
typedef struct lws_metrics_tag	lws_metrics_tag_t
typedef struct lws_metric_bucket	lws_metric_bucket_t
typedef struct lws_metric_pub	lws_metric_pub_t
typedef struct lws_metric_caliper	lws_metric_caliper_t
typedef enum lws_metric_rpt	lws_metric_rpt_kind_t

Enumerations
enum	{   LWSMTFL_REPORT_OUTLIERS = (1 << 0) , LWSMTFL_REPORT_OOB = (1 << 1) , LWSMTFL_REPORT_INACTIVITY_AT_PERIODIC = (1 << 2) , LWSMTFL_REPORT_MEAN = (1 << 3) ,   LWSMTFL_REPORT_ONLY_GO = (1 << 4) , LWSMTFL_REPORT_DUTY_WALLCLOCK_US = (1 << 5) , LWSMTFL_REPORT_HIST = (1 << 6) }
enum	{ LMT_NORMAL = 0 , LMT_OUTLIER , LMT_FAIL , LMT_COUNT }
enum	lws_metric_rpt { LMR_PERIODIC = 0 , LMR_OUTLIER }

Functions
LWS_EXTERN LWS_VISIBLE int	lws_metrics_tag_add (lws_dll2_owner_t *owner, const char *name, const char *val)
LWS_EXTERN LWS_VISIBLE void	lws_metrics_tags_destroy (lws_dll2_owner_t *owner)
LWS_EXTERN LWS_VISIBLE size_t	lws_metrics_tags_serialize (lws_dll2_owner_t *owner, char *buf, size_t len)
LWS_EXTERN LWS_VISIBLE const char *	lws_metrics_tag_get (lws_dll2_owner_t *owner, const char *name)
LWS_EXTERN LWS_VISIBLE void	lws_metrics_hist_bump_priv_tagged (lws_metric_pub_t *mt, lws_dll2_owner_t *tow, lws_dll2_owner_t *tow2)
LWS_EXTERN LWS_VISIBLE int	lws_metrics_format (lws_metric_pub_t *pub, lws_metric_bucket_t **sub, char *buf, size_t len)
LWS_EXTERN LWS_VISIBLE int	lws_metrics_hist_bump_ (lws_metric_pub_t *pub, const char *name)
LWS_VISIBLE LWS_EXTERN int	lws_metrics_foreach (struct lws_context *ctx, void *user, int(*cb)(lws_metric_pub_t *pub, void *user))
LWS_VISIBLE LWS_EXTERN int	lws_metrics_hist_bump_describe_wsi (struct lws *wsi, lws_metric_pub_t *pub, const char *name)

---

Data Structure Documentation

lws_metrics_tag

struct lws_metrics_tag

Definition at line 71 of file lws-metrics.h.

Collaboration diagram for lws_metrics_tag:

Data Fields
lws_dll2_t	list
const char *	name

lws_metric_bucket

struct lws_metric_bucket

Definition at line 116 of file lws-metrics.h.

Collaboration diagram for lws_metric_bucket:

Data Fields
struct lws_metric_bucket *	next
uint64_t	count

lws_metric_pub

struct lws_metric_pub

Definition at line 154 of file lws-metrics.h.

Collaboration diagram for lws_metric_pub:

Data Fields
const char *	name	eg, "n.cn.dns", "vh.myendpoint"
void *	backend_opaque	ignored by lws, backend handler completely owns it
lws_usec_t	us_first	us time metric started collecting, reset to us_dumped at dump
lws_usec_t	us_last	0, or us time last event, reset to 0 at last dump
lws_usec_t	us_dumped	0 if never, else us time of last dump to external api
union lws_metric_pub	u
uint8_t	flags

lws_metric_caliper

struct lws_metric_caliper

Definition at line 217 of file lws-metrics.h.

Collaboration diagram for lws_metric_caliper:

Data Fields
struct lws_dll2_owner	mtags_owner	collect tags here during caliper lifetime
struct lws_metric *	mt	NULL == inactive
lws_usec_t	us_start

lws_metric_pub.u

union lws_metric_pub.u

Definition at line 169 of file lws-metrics.h.

Collaboration diagram for lws_metric_pub.u:

Data Fields
u	agg
u	hist

lws_metric_pub.u.agg

struct lws_metric_pub.u.agg

Definition at line 172 of file lws-metrics.h.

Collaboration diagram for lws_metric_pub.u.agg:

Data Fields
u_mt_t	sum[2]	go, no-go summed for mean or plan sum
u_mt_t	min	smallest individual measurement
u_mt_t	max	largest individual measurement
uint32_t	count[2]	go, no-go count of measurements in sum

lws_metric_pub.u.hist

struct lws_metric_pub.u.hist

Definition at line 186 of file lws-metrics.h.

Collaboration diagram for lws_metric_pub.u.hist:

Data Fields
lws_metric_bucket_t *	head	first bucket in our bucket list
uint64_t	total_count	total count in all of our buckets
uint32_t	list_size	number of buckets in our bucket list

Macro Definition Documentation

lws_metrics_tag_wsi_add

#define lws_metrics_tag_wsi_add	(		_a,
			_b,
			_c
	)

Definition at line 89 of file lws-metrics.h.

lws_metric_bucket_name_len

#define lws_metric_bucket_name_len

(

_b

)

(*((uint8_t *)&(_b)[1]))

Definition at line 124 of file lws-metrics.h.

lws_metric_bucket_name

#define lws_metric_bucket_name

(

_b

)

(((const char *)&(_b)[1]) + 1)

Definition at line 125 of file lws-metrics.h.

lws_metrics_caliper_compose

#define lws_metrics_caliper_compose

(

_name

)

Definition at line 255 of file lws-metrics.h.

lws_metrics_caliper_bind

#define lws_metrics_caliper_bind	(		_name,
			_mt
	)

Definition at line 256 of file lws-metrics.h.

lws_metrics_caliper_declare

#define lws_metrics_caliper_declare	(		_name,
			_mp
	)

Definition at line 257 of file lws-metrics.h.

lws_metrics_caliper_report

#define lws_metrics_caliper_report	(		_name,
			_go_nogo
	)

Definition at line 258 of file lws-metrics.h.

lws_metrics_caliper_report_hist

#define lws_metrics_caliper_report_hist	(		_name,
			pwsiconn
	)

Definition at line 259 of file lws-metrics.h.

lws_metrics_caliper_cancel

#define lws_metrics_caliper_cancel

(

_name

)

Definition at line 260 of file lws-metrics.h.

lws_metrics_hist_bump

#define lws_metrics_hist_bump	(		_mt,
			_name
	)

Definition at line 261 of file lws-metrics.h.

lws_metrics_hist_bump_priv

#define lws_metrics_hist_bump_priv	(		_mt,
			_name
	)

Definition at line 262 of file lws-metrics.h.

lws_metrics_caliper_done

#define lws_metrics_caliper_done

(

_name

)

Definition at line 263 of file lws-metrics.h.

METRES_GO

#define METRES_GO   0

Definition at line 326 of file lws-metrics.h.

METRES_NOGO

#define METRES_NOGO   1

Definition at line 327 of file lws-metrics.h.

Typedef Documentation

u_mt_t

typedef uint64_t u_mt_t

Definition at line 29 of file lws-metrics.h.

lws_metrics_tag_t

typedef struct lws_metrics_tag lws_metrics_tag_t

lws_metric_bucket_t

typedef struct lws_metric_bucket lws_metric_bucket_t

lws_metric_pub_t

typedef struct lws_metric_pub lws_metric_pub_t

lws_metric_caliper_t

typedef struct lws_metric_caliper lws_metric_caliper_t

lws_metric_rpt_kind_t

typedef enum lws_metric_rpt lws_metric_rpt_kind_t

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
LWSMTFL_REPORT_OUTLIERS	track outliers and report them internally
LWSMTFL_REPORT_OOB	report events as they happen
LWSMTFL_REPORT_INACTIVITY_AT_PERIODIC	explicitly externally report no activity at periodic cb, by default no events in the period is just not reported
LWSMTFL_REPORT_MEAN	average/min/max is meaningful, else only sum is meaningful
LWSMTFL_REPORT_ONLY_GO	no-go pieces invalid
LWSMTFL_REPORT_DUTY_WALLCLOCK_US	aggregate compares to wallclock us for duty cycle
LWSMTFL_REPORT_HIST	our type is histogram (otherwise, sum / mean aggregation)

Definition at line 31 of file lws-metrics.h.

     {
        LWSMTFL_REPORT_OUTLIERS                         = (1 << 0),
        LWSMTFL_REPORT_OOB                              = (1 << 1),
        LWSMTFL_REPORT_INACTIVITY_AT_PERIODIC           = (1 << 2),
        LWSMTFL_REPORT_MEAN                             = (1 << 3),
        LWSMTFL_REPORT_ONLY_GO                          = (1 << 4),
        LWSMTFL_REPORT_DUTY_WALLCLOCK_US                = (1 << 5),
        LWSMTFL_REPORT_HIST                             = (1 << 6),
};

anonymous enum

anonymous enum

Enumerator
LMT_NORMAL
LMT_OUTLIER
LMT_FAIL
LMT_COUNT

Definition at line 312 of file lws-metrics.h.

     {
        LMT_NORMAL = 0, /* related to successful events */
        LMT_OUTLIER,    /* related to successful events outside of bounds */
 
        LMT_FAIL,       /* related to failed events */
 
        LMT_COUNT,
};

lws_metric_rpt

enum lws_metric_rpt

Enumerator
LMR_PERIODIC
LMR_OUTLIER

Definition at line 321 of file lws-metrics.h.

                            {
        LMR_PERIODIC = 0,       /* we are reporting on a schedule */
        LMR_OUTLIER,            /* we are reporting the last outlier */
} lws_metric_rpt_kind_t;

Function Documentation

lws_metrics_tag_add()

LWS_EXTERN LWS_VISIBLE int lws_metrics_tag_add	(	lws_dll2_owner_t *	owner,
		const char *	name,
		const char *	val
	)

lws_metrics_tags_destroy()

LWS_EXTERN LWS_VISIBLE void lws_metrics_tags_destroy

(

lws_dll2_owner_t *

owner

)

lws_metrics_tags_serialize()

LWS_EXTERN LWS_VISIBLE size_t lws_metrics_tags_serialize	(	lws_dll2_owner_t *	owner,
		char *	buf,
		size_t	len
	)

lws_metrics_tag_get()

LWS_EXTERN LWS_VISIBLE const char* lws_metrics_tag_get	(	lws_dll2_owner_t *	owner,
		const char *	name
	)

lws_metrics_hist_bump_priv_tagged()

LWS_EXTERN LWS_VISIBLE void lws_metrics_hist_bump_priv_tagged	(	lws_metric_pub_t *	mt,
		lws_dll2_owner_t *	tow,
		lws_dll2_owner_t *	tow2
	)

lws_metrics_format()

LWS_EXTERN LWS_VISIBLE int lws_metrics_format	(	lws_metric_pub_t *	pub,
		lws_metric_bucket_t **	sub,
		char *	buf,
		size_t	len
	)

lws_metrics_format() - helper to format a metrics object for logging

Parameters

pub	public part of metrics object
buf	output buffer to place string in
len	available length of buf

Helper for describing the state of a metrics object as a human-readable string, accounting for how its flags indicate what it contains. This is not how you would report metrics, but during development it can be useful to log them inbetween possibily long report intervals.

It uses the metric's flags to adapt the format shown appropriately, eg, as a histogram if LWSMTFL_REPORT_HIST etc

lws_metrics_hist_bump_()

LWS_EXTERN LWS_VISIBLE int lws_metrics_hist_bump_	(	lws_metric_pub_t *	pub,
		const char *	name
	)

lws_metrics_hist_bump() - add or increment histogram bucket

Parameters

pub	public part of metrics object
name	bucket name to increment

Either increment the count of an existing bucket of the right name in the metrics object, or add a new bucket of the given name and set its count to 1.

The metrics object must have been created with flag LWSMTFL_REPORT_HIST

Normally, you will actually use the preprocessor wrapper lws_metrics_hist_bump() defined above, since this automatically takes care of removing itself from the build if WITH_SYS_METRICS is not defined, without needing any preprocessor conditionals.

lws_metrics_foreach()

LWS_VISIBLE LWS_EXTERN int lws_metrics_foreach	(	struct lws_context *	ctx,
		void *	user,
		int(*)(lws_metric_pub_t *pub, void *user)	cb
	)

lws_metrics_hist_bump_describe_wsi()

LWS_VISIBLE LWS_EXTERN int lws_metrics_hist_bump_describe_wsi	(	struct lws *	wsi,
		lws_metric_pub_t *	pub,
		const char *	name
	)