1/*
2 * lws System Metrics
3 *
4 * Copyright (C) 2021 Andy Green <andy@warmcat.com>
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22 * IN THE SOFTWARE.
23 */
24
25/*
26 * Const struct that describes a policy for processing raw metrics to turn them
27 * into events.
28 *
29 * Typically although we want to monitor every event, the data produced can be
30 * too large, and many events that are "normal" just need to be counted as such;
31 * outliers or change-to-continuous outliers may deserve closer recording as
32 * events in their own right.
33 *
34 * Mean computation must "decay" as it ages, we do this by halving the sum and
35 * count after .us_decay_unit us.
36 *
37 * We don't acknowledge outliers until there are at least .min_contributors
38 * in the current mean (which is subject to decaying)
39 *
40 * We decide something is an outlier event if it deviates from the mean by
41 * .pc_outlier_deviation %.
42 */
43
44/*
45 * The dynamic counterpart for each static metric policy, this is on heap
46 * one per const lws_metric_policy_t.  It's listed in context->owner_mtr_dynpol
47 */
48
49typedef struct lws_metric_policy_dyn {
50	const lws_metric_policy_t	*policy;
51	/**< the static part of the policy we belong to... can be NULL if no
52	 * policy matches or the policy was invalidated */
53
54	lws_dll2_owner_t		owner;
55	/**< list of metrics that are using this policy */
56
57	lws_dll2_t			list;
58	/**< context owns us */
59
60	lws_sorted_usec_list_t		sul;
61	/**< schedule periodic reports for metrics using this policy */
62} lws_metric_policy_dyn_t;
63
64/*
65 * A metrics private part, encapsulating the public part
66 */
67
68typedef struct lws_metric {
69
70	lws_dll2_t			list;
71	/**< owned by either 1) ctx.lws_metric_policy_dyn_t.owner, or
72	 * 2) ctx.owner_mtr_no_pol */
73
74	struct lws_context		*ctx;
75
76	/* public part overallocated */
77} lws_metric_t;
78
79
80#if defined(LWS_WITH_SYS_METRICS)
81#define lws_metrics_hist_bump_priv(_mt, _name) \
82		lws_metrics_hist_bump_(lws_metrics_priv_to_pub(_mt), _name)
83#define lws_metrics_hist_bump_priv_wsi(_wsi, _hist, _name) \
84		lws_metrics_hist_bump_(lws_metrics_priv_to_pub(_wsi->a.context->_hist), _name)
85#define lws_metrics_hist_bump_priv_ss(_ss, _hist, _name) \
86		lws_metrics_hist_bump_(lws_metrics_priv_to_pub(_ss->context->_hist), _name)
87#define lws_metrics_priv_to_pub(_x) ((lws_metric_pub_t *)&(_x)[1])
88#else
89#define lws_metrics_hist_bump_priv(_mt, _name)
90#define lws_metrics_hist_bump_priv_wsi(_wsi, _hist, _name)
91#define lws_metrics_hist_bump_priv_ss(_ss, _hist, _name)
92#define lws_metrics_priv_to_pub(_x) ((lws_metric_pub_t *)NULL)
93#endif
94
95#if defined(LWS_WITH_SECURE_STREAMS_PROXY_API)
96/*
97 * sspc-specific version that also appends the tag value to the lifecycle tag
98 * used for logging the sspc identity
99 */
100int
101lws_metrics_tag_sspc_add(struct lws_sspc_handle *ss, const char *name, const char *val);
102#endif
103
104int
105lws_metrics_register_policy(struct lws_context *ctx,
106			    const lws_metric_policy_t *head);
107
108void
109lws_metrics_destroy(struct lws_context *ctx);
110
111void
112lws_metric_event(lws_metric_t *mt, char go_nogo, u_mt_t val);
113
114lws_metric_t *
115lws_metric_create(struct lws_context *ctx, uint8_t flags, const char *name);
116
117int
118lws_metric_destroy(lws_metric_t **mt, int keep);
119
120void
121lws_metric_policy_dyn_destroy(lws_metric_policy_dyn_t *dm, int keep);
122
123void
124lws_metric_rebind_policies(struct lws_context *ctx);
125