[lttng-tools.git] / include / lttng / condition / buffer-usage.h

/*
 * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-only
 *
 */

#ifndef LTTNG_CONDITION_BUFFER_USAGE_H
#define LTTNG_CONDITION_BUFFER_USAGE_H

#include <lttng/condition/condition.h>
#include <lttng/condition/evaluation.h>
#include <lttng/domain.h>
#include <lttng/lttng-export.h>

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Buffer usage conditions allows an action to be taken whenever a channel's
 * buffer usage crosses a set threshold.
 *
 * These conditions are periodically evaluated against the current buffer
 * usage statistics. The period at which these conditions are evaluated is
 * governed by the channels' monitor timer.
 *
 * Note that the use of these conditons does not imply any hysteresis-loop
 * mechanism. For instance, an upper-bound buffer usage condition set to 75%
 * will fire everytime the buffer usage goes from a value < 75% to a value that
 * is >= 75%. The evaluation result does not depend on any lower-bound condition
 * being reached before the condition is evaluated to true again.
 *
 * Buffer usage conditions have the following properties:
 *   - the exact name of the session in which the channel to be monitored is
 *     defined,
 *   - the domain of the channel to be monitored,
 *   - the exact name of the channel to be monitored,
 *   - a usage threshold, expressed either in bytes or as a fraction of total
 *     buffer capacity.
 *
 * Wildcards, regular expressions or other globbing mechanisms are not supported
 * in buffer usage condition properties.
 */

/*
 * Create a newly allocated lower-bound buffer usage condition.
 *
 * A lower-bound buffer usage condition evaluates to true whenever
 * a buffer's usage _crosses_ the bound that is defined as part of the
 * condition's properties from high to low. In other words, the condition only
 * evaluates to true when a buffer's usage transitions from a value higher than
 * the threshold defined in the condition to a value lower than the threshold
 * defined in the condition.
 *
 * Returns a new condition on success, NULL on failure. This condition must be
 * destroyed using lttng_condition_destroy().
 */
LTTNG_EXPORT extern struct lttng_condition *lttng_condition_buffer_usage_low_create(void);

/*
 * Create a newly allocated upper-bound buffer usage condition.
 *
 * An upper-bound buffer usage condition evaluates to true whenever
 * a buffer's usage _crosses_ the bound that is defined as part of the
 * condition's properties from low to high. In other words, the condition only
 * evaluates to true when a buffer's usage transitions from a value lower than
 * the threshold defined in the condition to a value higher than the threshold
 * defined in the condition.
 *
 * Returns a new condition on success, NULL on failure. This condition must be
 * destroyed using lttng_condition_destroy().
 */
LTTNG_EXPORT extern struct lttng_condition *lttng_condition_buffer_usage_high_create(void);

/*
 * Get the buffer usage threshold ratio of a buffer usage condition.
 *
 * The buffer usage condition's threshold must have been defined as a ratio in
 * order for this call to succeed.
 *
 * Returns LTTNG_CONDITION_STATUS_OK on success and a ratio contained by the
 * interval [0.0, 1.0]. LTTNG_CONDITION_STATUS_INVALID is returned if an invalid
 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a threshold,
 * expressed as a ratio of total buffer capacity, was not set prior to this
 * call.
 */
LTTNG_EXPORT extern enum lttng_condition_status
lttng_condition_buffer_usage_get_threshold_ratio(const struct lttng_condition *condition,
						 double *threshold_ratio);

/*
 * Set the buffer usage threshold ratio of a buffer usage condition.
 *
 * The threshold ratio passed must be contained by the interval [0.0, 1.0] and
 * represents a ratio of the channel's buffer's capacity. Setting a threshold,
 * either as a ratio or as an absolute size in bytes will override any
 * previously set threshold.
 *
 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
 * if invalid paramenters are passed.
 */
LTTNG_EXPORT extern enum lttng_condition_status
lttng_condition_buffer_usage_set_threshold_ratio(struct lttng_condition *condition,
						 double threshold_ratio);

/*
 * Get the buffer usage threshold of a buffer usage condition.
 *
 * The buffer usage condition's threshold must have been defined as an absolute
 * value expressed in bytes in order for this call to succeed.
 *
 * Returns LTTNG_CONDITION_STATUS_OK on success and a threshold expressed in
 * bytes, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed, or
 * LTTNG_CONDITION_STATUS_UNSET if a threshold, expressed as an absolute size in
 * bytes, was not set prior to this call.
 */
LTTNG_EXPORT extern enum lttng_condition_status
lttng_condition_buffer_usage_get_threshold(const struct lttng_condition *condition,
					   uint64_t *threshold_bytes);

/*
 * Set the buffer usage threshold in bytes of a buffer usage condition.
 *
 * Setting a threshold, either as a ratio or as an absolute size in bytes
 * will override any previously set threshold.
 *
 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
 * if invalid paramenters are passed.
 */
LTTNG_EXPORT extern enum lttng_condition_status
lttng_condition_buffer_usage_set_threshold(struct lttng_condition *condition,
					   uint64_t threshold_bytes);

/*
 * Get the session name property of a buffer usage condition.
 *
 * The caller does not assume the ownership of the returned session name. The
 * session name shall only only be used for the duration of the condition's
 * lifetime, or before a different session name is set.
 *
 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's session
 * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a session name
 * was not set prior to this call.
 */
LTTNG_EXPORT extern enum lttng_condition_status
lttng_condition_buffer_usage_get_session_name(const struct lttng_condition *condition,
					      const char **session_name);

/*
 * Set the session name property of a buffer usage condition.
 *
 * The passed session name parameter will be copied to the condition.
 *
 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
 * if invalid paramenters are passed.
 */
LTTNG_EXPORT extern enum lttng_condition_status
lttng_condition_buffer_usage_set_session_name(struct lttng_condition *condition,
					      const char *session_name);

/*
 * Get the channel name property of a buffer usage condition.
 *
 * The caller does not assume the ownership of the returned channel name. The
 * channel name shall only only be used for the duration of the condition's
 * lifetime, or before a different channel name is set.
 *
 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's channel
 * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a channel name
 * was not set prior to this call.
 */
LTTNG_EXPORT extern enum lttng_condition_status
lttng_condition_buffer_usage_get_channel_name(const struct lttng_condition *condition,
					      const char **channel_name);

/*
 * Set the channel name property of a buffer usage condition.
 *
 * The passed channel name parameter will be copied to the condition.
 *
 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
 * if invalid paramenters are passed.
 */
LTTNG_EXPORT extern enum lttng_condition_status
lttng_condition_buffer_usage_set_channel_name(struct lttng_condition *condition,
					      const char *channel_name);

/*
 * Get the domain type property of a buffer usage condition.
 *
 * Returns LTTNG_CONDITION_STATUS_OK and sets the domain type output parameter
 * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed,
 * or LTTNG_CONDITION_STATUS_UNSET if a domain type was not set prior to this
 * call.
 */
LTTNG_EXPORT extern enum lttng_condition_status
lttng_condition_buffer_usage_get_domain_type(const struct lttng_condition *condition,
					     enum lttng_domain_type *type);

/*
 * Set the domain type property of a buffer usage condition.
 *
 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
 * if invalid paramenters are passed.
 */
LTTNG_EXPORT extern enum lttng_condition_status
lttng_condition_buffer_usage_set_domain_type(struct lttng_condition *condition,
					     enum lttng_domain_type type);

/**
 * lttng_evaluation_buffer_usage are specialised lttng_evaluations which
 * allow users to query a number of properties resulting from the evaluation
 * of a condition which evaluated to true.
 *
 * The evaluation of a buffer usage condition yields two different results:
 *   - the usage ratio of the channel buffers at the time of the evaluation,
 *   - the usage, in bytes, of the channel buffers at the time of evaluation.
 */

/*
 * Get the buffer usage ratio property of a buffer usage evaluation.
 *
 * Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed as
 * as a ratio of the buffer's capacity, or LTTNG_EVALUATION_STATUS_INVALID if
 * an invalid parameter is passed.
 */
LTTNG_EXPORT extern enum lttng_evaluation_status
lttng_evaluation_buffer_usage_get_usage_ratio(const struct lttng_evaluation *evaluation,
					      double *usage_ratio);

/*
 * Get the buffer usage property of a buffer usage evaluation.
 *
 * Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed in
 * bytes, or LTTNG_EVALUATION_STATUS_INVALID if an invalid parameter is passed.
 */
LTTNG_EXPORT extern enum lttng_evaluation_status
lttng_evaluation_buffer_usage_get_usage(const struct lttng_evaluation *evaluation,
					uint64_t *usage_bytes);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_CONDITION_BUFFER_USAGE_H */
Commit	Line	Data
a58c490f	1	/*
ab5be9fa	2	* Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
a58c490f	3	*
ab5be9fa	4	* SPDX-License-Identifier: LGPL-2.1-only
a58c490f	5	*
a58c490f JG	6	*/
	7
	8	#ifndef LTTNG_CONDITION_BUFFER_USAGE_H
	9	#define LTTNG_CONDITION_BUFFER_USAGE_H
	10
9d744342	11	#include <lttng/condition/condition.h>
28f23191	12	#include <lttng/condition/evaluation.h>
b3a57d53	13	#include <lttng/domain.h>
4bd69c5f	14	#include <lttng/lttng-export.h>
9d744342	15
28f23191 JG	16	#include <stdint.h>
28f23191 JG	17
a58c490f JG	18	#ifdef __cplusplus
	19	extern "C" {
	20	#endif
	21
888d24c6 JG	22	/**
	23	* Buffer usage conditions allows an action to be taken whenever a channel's
	24	* buffer usage crosses a set threshold.
	25	*
	26	* These conditions are periodically evaluated against the current buffer
	27	* usage statistics. The period at which these conditions are evaluated is
	28	* governed by the channels' monitor timer.
	29	*
	30	* Note that the use of these conditons does not imply any hysteresis-loop
	31	* mechanism. For instance, an upper-bound buffer usage condition set to 75%
	32	* will fire everytime the buffer usage goes from a value < 75% to a value that
	33	* is >= 75%. The evaluation result does not depend on any lower-bound condition
	34	* being reached before the condition is evaluated to true again.
	35	*
	36	* Buffer usage conditions have the following properties:
	37	* - the exact name of the session in which the channel to be monitored is
	38	* defined,
	39	* - the domain of the channel to be monitored,
	40	* - the exact name of the channel to be monitored,
	41	* - a usage threshold, expressed either in bytes or as a fraction of total
	42	* buffer capacity.
	43	*
	44	* Wildcards, regular expressions or other globbing mechanisms are not supported
	45	* in buffer usage condition properties.
	46	*/
	47
	48	/*
	49	* Create a newly allocated lower-bound buffer usage condition.
	50	*
	51	* A lower-bound buffer usage condition evaluates to true whenever
	52	* a buffer's usage _crosses_ the bound that is defined as part of the
	53	* condition's properties from high to low. In other words, the condition only
	54	* evaluates to true when a buffer's usage transitions from a value higher than
	55	* the threshold defined in the condition to a value lower than the threshold
	56	* defined in the condition.
	57	*
	58	* Returns a new condition on success, NULL on failure. This condition must be
	59	* destroyed using lttng_condition_destroy().
	60	*/
28f23191	61	LTTNG_EXPORT extern struct lttng_condition *lttng_condition_buffer_usage_low_create(void);
a58c490f	62
888d24c6 JG	63	/*
	64	* Create a newly allocated upper-bound buffer usage condition.
	65	*
	66	* An upper-bound buffer usage condition evaluates to true whenever
	67	* a buffer's usage _crosses_ the bound that is defined as part of the
	68	* condition's properties from low to high. In other words, the condition only
	69	* evaluates to true when a buffer's usage transitions from a value lower than
	70	* the threshold defined in the condition to a value higher than the threshold
	71	* defined in the condition.
	72	*
	73	* Returns a new condition on success, NULL on failure. This condition must be
	74	* destroyed using lttng_condition_destroy().
	75	*/
28f23191	76	LTTNG_EXPORT extern struct lttng_condition *lttng_condition_buffer_usage_high_create(void);
a58c490f	77
888d24c6 JG	78	/*
	79	* Get the buffer usage threshold ratio of a buffer usage condition.
	80	*
	81	* The buffer usage condition's threshold must have been defined as a ratio in
	82	* order for this call to succeed.
	83	*
	84	* Returns LTTNG_CONDITION_STATUS_OK on success and a ratio contained by the
	85	* interval [0.0, 1.0]. LTTNG_CONDITION_STATUS_INVALID is returned if an invalid
	86	* parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a threshold,
	87	* expressed as a ratio of total buffer capacity, was not set prior to this
	88	* call.
	89	*/
4bd69c5f	90	LTTNG_EXPORT extern enum lttng_condition_status
28f23191 JG	91	lttng_condition_buffer_usage_get_threshold_ratio(const struct lttng_condition *condition,
28f23191 JG	92	double *threshold_ratio);
a58c490f	93
888d24c6 JG	94	/*
	95	* Set the buffer usage threshold ratio of a buffer usage condition.
	96	*
	97	* The threshold ratio passed must be contained by the interval [0.0, 1.0] and
	98	* represents a ratio of the channel's buffer's capacity. Setting a threshold,
	99	* either as a ratio or as an absolute size in bytes will override any
	100	* previously set threshold.
	101	*
	102	* Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
	103	* if invalid paramenters are passed.
	104	*/
4bd69c5f	105	LTTNG_EXPORT extern enum lttng_condition_status
28f23191 JG	106	lttng_condition_buffer_usage_set_threshold_ratio(struct lttng_condition *condition,
28f23191 JG	107	double threshold_ratio);
a58c490f	108
888d24c6 JG	109	/*
	110	* Get the buffer usage threshold of a buffer usage condition.
	111	*
	112	* The buffer usage condition's threshold must have been defined as an absolute
	113	* value expressed in bytes in order for this call to succeed.
	114	*
	115	* Returns LTTNG_CONDITION_STATUS_OK on success and a threshold expressed in
	116	* bytes, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed, or
	117	* LTTNG_CONDITION_STATUS_UNSET if a threshold, expressed as an absolute size in
	118	* bytes, was not set prior to this call.
	119	*/
4bd69c5f	120	LTTNG_EXPORT extern enum lttng_condition_status
28f23191 JG	121	lttng_condition_buffer_usage_get_threshold(const struct lttng_condition *condition,
28f23191 JG	122	uint64_t *threshold_bytes);
a58c490f	123
888d24c6 JG	124	/*
	125	* Set the buffer usage threshold in bytes of a buffer usage condition.
	126	*
	127	* Setting a threshold, either as a ratio or as an absolute size in bytes
	128	* will override any previously set threshold.
	129	*
	130	* Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
	131	* if invalid paramenters are passed.
	132	*/
4bd69c5f	133	LTTNG_EXPORT extern enum lttng_condition_status
28f23191 JG	134	lttng_condition_buffer_usage_set_threshold(struct lttng_condition *condition,
28f23191 JG	135	uint64_t threshold_bytes);
a58c490f	136
888d24c6 JG	137	/*
	138	* Get the session name property of a buffer usage condition.
	139	*
	140	* The caller does not assume the ownership of the returned session name. The
	141	* session name shall only only be used for the duration of the condition's
	142	* lifetime, or before a different session name is set.
	143	*
	144	* Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's session
	145	* name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
	146	* parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a session name
	147	* was not set prior to this call.
	148	*/
4bd69c5f	149	LTTNG_EXPORT extern enum lttng_condition_status
28f23191 JG	150	lttng_condition_buffer_usage_get_session_name(const struct lttng_condition *condition,
28f23191 JG	151	const char **session_name);
a58c490f	152
888d24c6 JG	153	/*
	154	* Set the session name property of a buffer usage condition.
	155	*
	156	* The passed session name parameter will be copied to the condition.
	157	*
	158	* Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
	159	* if invalid paramenters are passed.
	160	*/
4bd69c5f	161	LTTNG_EXPORT extern enum lttng_condition_status
28f23191 JG	162	lttng_condition_buffer_usage_set_session_name(struct lttng_condition *condition,
28f23191 JG	163	const char *session_name);
a58c490f	164
888d24c6 JG	165	/*
	166	* Get the channel name property of a buffer usage condition.
	167	*
	168	* The caller does not assume the ownership of the returned channel name. The
	169	* channel name shall only only be used for the duration of the condition's
	170	* lifetime, or before a different channel name is set.
	171	*
	172	* Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's channel
	173	* name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
	174	* parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a channel name
	175	* was not set prior to this call.
	176	*/
4bd69c5f	177	LTTNG_EXPORT extern enum lttng_condition_status
28f23191 JG	178	lttng_condition_buffer_usage_get_channel_name(const struct lttng_condition *condition,
28f23191 JG	179	const char **channel_name);
a58c490f	180
888d24c6 JG	181	/*
	182	* Set the channel name property of a buffer usage condition.
	183	*
	184	* The passed channel name parameter will be copied to the condition.
	185	*
	186	* Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
	187	* if invalid paramenters are passed.
	188	*/
4bd69c5f	189	LTTNG_EXPORT extern enum lttng_condition_status
28f23191 JG	190	lttng_condition_buffer_usage_set_channel_name(struct lttng_condition *condition,
28f23191 JG	191	const char *channel_name);
a58c490f	192
888d24c6 JG	193	/*
	194	* Get the domain type property of a buffer usage condition.
	195	*
	196	* Returns LTTNG_CONDITION_STATUS_OK and sets the domain type output parameter
	197	* on success, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed,
	198	* or LTTNG_CONDITION_STATUS_UNSET if a domain type was not set prior to this
	199	* call.
	200	*/
4bd69c5f	201	LTTNG_EXPORT extern enum lttng_condition_status
28f23191 JG	202	lttng_condition_buffer_usage_get_domain_type(const struct lttng_condition *condition,
28f23191 JG	203	enum lttng_domain_type *type);
a58c490f	204
888d24c6 JG	205	/*
	206	* Set the domain type property of a buffer usage condition.
	207	*
	208	* Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
	209	* if invalid paramenters are passed.
	210	*/
4bd69c5f	211	LTTNG_EXPORT extern enum lttng_condition_status
28f23191 JG	212	lttng_condition_buffer_usage_set_domain_type(struct lttng_condition *condition,
28f23191 JG	213	enum lttng_domain_type type);
a58c490f	214
888d24c6 JG	215	/**
	216	* lttng_evaluation_buffer_usage are specialised lttng_evaluations which
	217	* allow users to query a number of properties resulting from the evaluation
	218	* of a condition which evaluated to true.
	219	*
	220	* The evaluation of a buffer usage condition yields two different results:
	221	* - the usage ratio of the channel buffers at the time of the evaluation,
	222	* - the usage, in bytes, of the channel buffers at the time of evaluation.
	223	*/
	224
	225	/*
	226	* Get the buffer usage ratio property of a buffer usage evaluation.
	227	*
cc02b9d4 JG	228	* Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed as
cc02b9d4 JG	229	* as a ratio of the buffer's capacity, or LTTNG_EVALUATION_STATUS_INVALID if
888d24c6 JG	230	* an invalid parameter is passed.
888d24c6 JG	231	*/
4bd69c5f	232	LTTNG_EXPORT extern enum lttng_evaluation_status
28f23191 JG	233	lttng_evaluation_buffer_usage_get_usage_ratio(const struct lttng_evaluation *evaluation,
28f23191 JG	234	double *usage_ratio);
a58c490f	235
888d24c6 JG	236	/*
	237	* Get the buffer usage property of a buffer usage evaluation.
	238	*
cc02b9d4 JG	239	* Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed in
cc02b9d4 JG	240	* bytes, or LTTNG_EVALUATION_STATUS_INVALID if an invalid parameter is passed.
888d24c6	241	*/
4bd69c5f	242	LTTNG_EXPORT extern enum lttng_evaluation_status
28f23191 JG	243	lttng_evaluation_buffer_usage_get_usage(const struct lttng_evaluation *evaluation,
28f23191 JG	244	uint64_t *usage_bytes);
a58c490f JG	245
	246	#ifdef __cplusplus
	247	}
	248	#endif
	249
	250	#endif /* LTTNG_CONDITION_BUFFER_USAGE_H */