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

/*
 * Copyright (C) 2017 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License, version 2.1 only,
 * as published by the Free Software Foundation.
 *
 * This library is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

#ifndef LTTNG_CONDITION_BUFFER_USAGE_H
#define LTTNG_CONDITION_BUFFER_USAGE_H

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