[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

struct lttng_condition;
struct lttng_evaluation;

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