libwebsockets
Lightweight C library for HTML5 websockets
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 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
struct lws_metric_pub.u.agg agg
struct lws_metric_pub.u.hist 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

◆ lws_metric_bucket_t

◆ lws_metric_pub_t

◆ lws_metric_caliper_t

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

31 {
32 LWSMTFL_REPORT_OUTLIERS = (1 << 0),
34 LWSMTFL_REPORT_OOB = (1 << 1),
39 LWSMTFL_REPORT_MEAN = (1 << 3),
41 LWSMTFL_REPORT_ONLY_GO = (1 << 4),
45 LWSMTFL_REPORT_HIST = (1 << 6),
47};
@ LWSMTFL_REPORT_OUTLIERS
Definition: lws-metrics.h:32
@ LWSMTFL_REPORT_ONLY_GO
Definition: lws-metrics.h:41
@ LWSMTFL_REPORT_INACTIVITY_AT_PERIODIC
Definition: lws-metrics.h:36
@ LWSMTFL_REPORT_OOB
Definition: lws-metrics.h:34
@ LWSMTFL_REPORT_HIST
Definition: lws-metrics.h:45
@ LWSMTFL_REPORT_DUTY_WALLCLOCK_US
Definition: lws-metrics.h:43
@ LWSMTFL_REPORT_MEAN
Definition: lws-metrics.h:39

◆ anonymous enum

anonymous enum
Enumerator
LMT_NORMAL 
LMT_OUTLIER 
LMT_FAIL 
LMT_COUNT 

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

312 {
313 LMT_NORMAL = 0, /* related to successful events */
314 LMT_OUTLIER, /* related to successful events outside of bounds */
315
316 LMT_FAIL, /* related to failed events */
317
318 LMT_COUNT,
319};
@ LMT_OUTLIER
Definition: lws-metrics.h:314
@ LMT_COUNT
Definition: lws-metrics.h:318
@ LMT_NORMAL
Definition: lws-metrics.h:313
@ LMT_FAIL
Definition: lws-metrics.h:316

◆ lws_metric_rpt

Enumerator
LMR_PERIODIC 
LMR_OUTLIER 

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

321 {
322 LMR_PERIODIC = 0, /* we are reporting on a schedule */
323 LMR_OUTLIER, /* we are reporting the last outlier */
@ LMR_PERIODIC
Definition: lws-metrics.h:322
@ LMR_OUTLIER
Definition: lws-metrics.h:323
enum lws_metric_rpt 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
pubpublic part of metrics object
bufoutput buffer to place string in
lenavailable 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
pubpublic part of metrics object
namebucket 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 
)