[lttng-tools.git] / include / lttng / condition / session-consumed-size.h

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

#ifndef LTTNG_CONDITION_SESSION_CONSUMED_SIZE_H
#define LTTNG_CONDITION_SESSION_CONSUMED_SIZE_H

#include <lttng/condition/evaluation.h>
#include <lttng/condition/condition.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Session consumed size conditions allow an action to be taken whenever a
 * session's produced data size crosses a set threshold.
 *
 * These conditions are periodically evaluated against the current session
 * statistics. The period at which these conditions are evaluated is
 * governed by the channels' monitor timer.
 *
 * Session consumed size conditions have the following properties:
 *   - the exact name of the session to be monitored,
 *   - a total consumed size threshold, expressed in bytes.
 *
 * Wildcards, regular expressions or other globbing mechanisms are not supported
 * in session consumed size condition properties.
 */

/*
 * Create a newly allocated session consumed size condition.
 *
 * A session consumed size condition evaluates to true whenever the sum of all
 * its channels' consumed data size is higher than a set threshold. The
 * consumed data sizes are free running counters.
 *
 * Returns a new condition on success, NULL on failure. This condition must be
 * destroyed using lttng_condition_destroy().
 */
extern struct lttng_condition *
lttng_condition_session_consumed_size_create(void);

/*
 * Get the threshold of a session consumed size condition.
 *
 * The session consumed size 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_session_consumed_size_get_threshold(
		const struct lttng_condition *condition,
	        uint64_t *consumed_threshold_bytes);

/*
 * Set the threshold of a session consumed size usage condition.
 *
 * Setting a threshold overrides any previously set threshold.
 *
 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
 * if invalid parameters are passed.
 */
extern enum lttng_condition_status
lttng_condition_session_consumed_size_set_threshold(
		struct lttng_condition *condition,
	        uint64_t consumed_threshold_bytes);

/*
 * Get the session name property of a session consumed size condition.
 *
 * The caller does not assume the ownership of the returned session name. The
 * session name shall 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_session_consumed_size_get_session_name(
		const struct lttng_condition *condition,
		const char **session_name);

/*
 * Set the session name property of a session consumed size 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 parameters are passed.
 */
extern enum lttng_condition_status
lttng_condition_session_consumed_size_set_session_name(
		struct lttng_condition *condition,
		const char *session_name);

/**
 * lttng_evaluation_session_consumed_size is specialised lttng_evaluations
 * which allow users to query a number of properties resulting from the
 * evaluation of a condition which evaluated to true.
 */

/*
 * Get the session consumed property of a session consumed size 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_session_consumed_size_get_consumed_size(
		const struct lttng_evaluation *evaluation,
	        uint64_t *session_consumed);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_CONDITION_SESSION_CONSUMED_SIZE_H */
Commit	Line	Data
e8360425	1	/*
ab5be9fa	2	* Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
e8360425	3	*
ab5be9fa	4	* SPDX-License-Identifier: LGPL-2.1-only
e8360425	5	*
e8360425 JD	6	*/
	7
	8	#ifndef LTTNG_CONDITION_SESSION_CONSUMED_SIZE_H
	9	#define LTTNG_CONDITION_SESSION_CONSUMED_SIZE_H
	10
	11	#include <lttng/condition/evaluation.h>
	12	#include <lttng/condition/condition.h>
	13	#include <stdint.h>
e8360425 JD	14
	15	#ifdef __cplusplus
	16	extern "C" {
	17	#endif
	18
e8360425 JD	19	/**
	20	* Session consumed size conditions allow an action to be taken whenever a
	21	* session's produced data size crosses a set threshold.
	22	*
	23	* These conditions are periodically evaluated against the current session
	24	* statistics. The period at which these conditions are evaluated is
	25	* governed by the channels' monitor timer.
	26	*
	27	* Session consumed size conditions have the following properties:
	28	* - the exact name of the session to be monitored,
	29	* - a total consumed size threshold, expressed in bytes.
	30	*
	31	* Wildcards, regular expressions or other globbing mechanisms are not supported
	32	* in session consumed size condition properties.
	33	*/
	34
	35	/*
	36	* Create a newly allocated session consumed size condition.
	37	*
	38	* A session consumed size condition evaluates to true whenever the sum of all
	39	* its channels' consumed data size is higher than a set threshold. The
	40	* consumed data sizes are free running counters.
	41	*
	42	* Returns a new condition on success, NULL on failure. This condition must be
	43	* destroyed using lttng_condition_destroy().
	44	*/
	45	extern struct lttng_condition *
	46	lttng_condition_session_consumed_size_create(void);
	47
	48	/*
	49	* Get the threshold of a session consumed size condition.
	50	*
	51	* The session consumed size condition's threshold must have been defined as
	52	* an absolute value expressed in bytes in order for this call to succeed.
	53	*
	54	* Returns LTTNG_CONDITION_STATUS_OK on success and a threshold expressed in
	55	* bytes, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed, or
	56	* LTTNG_CONDITION_STATUS_UNSET if a threshold, expressed as an absolute size in
	57	* bytes, was not set prior to this call.
	58	*/
	59	extern enum lttng_condition_status
	60	lttng_condition_session_consumed_size_get_threshold(
	61	const struct lttng_condition *condition,
	62	uint64_t *consumed_threshold_bytes);
	63
	64	/*
	65	* Set the threshold of a session consumed size usage condition.
	66	*
	67	* Setting a threshold overrides any previously set threshold.
	68	*
	69	* Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
	70	* if invalid parameters are passed.
	71	*/
	72	extern enum lttng_condition_status
	73	lttng_condition_session_consumed_size_set_threshold(
	74	struct lttng_condition *condition,
	75	uint64_t consumed_threshold_bytes);
	76
	77	/*
	78	* Get the session name property of a session consumed size condition.
	79	*
	80	* The caller does not assume the ownership of the returned session name. The
	81	* session name shall only be used for the duration of the condition's
	82	* lifetime, or before a different session name is set.
83	*
84	* Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's session
85	* name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
86	* parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a session name
87	* was not set prior to this call.
88	*/
89	extern enum lttng_condition_status
90	lttng_condition_session_consumed_size_get_session_name(
91	const struct lttng_condition *condition,
92	const char **session_name);
93
94	/*
95	* Set the session name property of a session consumed size condition.
96	*
97	* The passed session name parameter will be copied to the condition.
98	*
99	* Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
100	* if invalid parameters are passed.
101	*/
102	extern enum lttng_condition_status
103	lttng_condition_session_consumed_size_set_session_name(
104	struct lttng_condition *condition,
105	const char *session_name);
106
107	/**
108	* lttng_evaluation_session_consumed_size is specialised lttng_evaluations
109	* which allow users to query a number of properties resulting from the
110	* evaluation of a condition which evaluated to true.
111	*/
112
113	/*
114	* Get the session consumed property of a session consumed size evaluation.
115	*
cc02b9d4 JG	116	* Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed in
cc02b9d4 JG	117	* bytes, or LTTNG_EVALUATION_STATUS_INVALID if an invalid parameter is passed.
e8360425 JD	118	*/
	119	extern enum lttng_evaluation_status
	120	lttng_evaluation_session_consumed_size_get_consumed_size(
	121	const struct lttng_evaluation *evaluation,
	122	uint64_t *session_consumed);
	123
	124	#ifdef __cplusplus
	125	}
	126	#endif
	127
	128	#endif /* LTTNG_CONDITION_SESSION_CONSUMED_SIZE_H */