[lttng-tools.git] / include / lttng / condition / session-rotation.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_SESSION_ROTATION_H
#define LTTNG_CONDITION_SESSION_ROTATION_H

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

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Session rotation conditions allow an action to be taken whenever a
 * session rotation is ongoing or completed.
 *
 * Session rotation conditions have the following properties:
 *   - the exact name of the session to be monitored for rotations
 *
 * Wildcards, regular expressions or other globbing mechanisms are not supported
 * in session rotation condition properties.
 */

/*
 * Create a newly allocated session rotation in progress condition.
 *
 * A session rotation ongoing condition evaluates to true whenever a rotation
 * is ongoing for a given session.
 *
 * 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_rotation_ongoing_create(void);

/*
 * Create a newly allocated session rotation completion condition.
 *
 * A session rotation completed condition evaluates to true whenever a rotation
 * is completed for a given session. This condition is not evaluated on
 * subscription or registration of a trigger. This means that a trigger
 * using this condition will only fire when the next session rotation completes.
 * Previously completed rotations will have no effect.
 *
 * 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_rotation_completed_create(void);

/*
 * Get the session name property of a session rotation 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_session_rotation_get_session_name(
		const struct lttng_condition *condition,
		const char **session_name);

/*
 * Set the session name property of a session rotation 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_session_rotation_set_session_name(
		struct lttng_condition *condition,
		const char *session_name);

/**
 * lttng_evaluation_session_rotation are 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 rotation id property of a session rotation evaluation.
 *
 * Returns LTTNG_EVALUATION_STATUS_OK on success and the id of the session
 * rotation, or LTTNG_EVALUATION_STATUS_INVALID if an invalid parameter is
 * passed.
 */
extern enum lttng_evaluation_status
lttng_evaluation_session_rotation_get_id(
		const struct lttng_evaluation *evaluation, uint64_t *id);

/*
 * Get the session rotation location property of a session rotation completed
 * evaluation.
 *
 * The caller does not assume the ownership of the returned location. The
 * location shall only only be used for the duration of the evaluation's
 * lifetime.
 *
 * Returns LTTNG_EVALUATION_STATUS_OK and set location on success.
 * A NULL location may be returned if a rotation chunk's location
 * has expired.
 *
 * LTTNG_EVALUATION_STATUS_INVALID is returned if an invalid parameter is
 * passed.
 */
extern enum lttng_evaluation_status
lttng_evaluation_session_rotation_completed_get_location(
		const struct lttng_evaluation *evaluation,
		const struct lttng_trace_archive_location **location);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_CONDITION_SESSION_ROTATION_H */
Commit	Line	Data
c19092cd 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_SESSION_ROTATION_H
	19	#define LTTNG_CONDITION_SESSION_ROTATION_H
	20
	21	#include <lttng/condition/evaluation.h>
	22	#include <lttng/condition/condition.h>
	23	#include <stdint.h>
	24	#include <lttng/domain.h>
	25	#include <lttng/location.h>
	26
	27	#ifdef __cplusplus
	28	extern "C" {
	29	#endif
	30
	31	/**
	32	* Session rotation conditions allow an action to be taken whenever a
	33	* session rotation is ongoing or completed.
	34	*
	35	* Session rotation conditions have the following properties:
	36	* - the exact name of the session to be monitored for rotations
	37	*
	38	* Wildcards, regular expressions or other globbing mechanisms are not supported
	39	* in session rotation condition properties.
	40	*/
	41
	42	/*
	43	* Create a newly allocated session rotation in progress condition.
	44	*
	45	* A session rotation ongoing condition evaluates to true whenever a rotation
	46	* is ongoing for a given session.
	47	*
	48	* Returns a new condition on success, NULL on failure. This condition must be
	49	* destroyed using lttng_condition_destroy().
	50	*/
	51	extern struct lttng_condition *
	52	lttng_condition_session_rotation_ongoing_create(void);
	53
	54	/*
	55	* Create a newly allocated session rotation completion condition.
	56	*
	57	* A session rotation completed condition evaluates to true whenever a rotation
	58	* is completed for a given session. This condition is not evaluated on
	59	* subscription or registration of a trigger. This means that a trigger
	60	* using this condition will only fire when the next session rotation completes.
	61	* Previously completed rotations will have no effect.
	62	*
	63	* Returns a new condition on success, NULL on failure. This condition must be
	64	* destroyed using lttng_condition_destroy().
65	*/
66	extern struct lttng_condition *
67	lttng_condition_session_rotation_completed_create(void);
68
69	/*
70	* Get the session name property of a session rotation condition.
71	*
72	* The caller does not assume the ownership of the returned session name. The
73	* session name shall only only be used for the duration of the condition's
74	* lifetime, or before a different session name is set.
75	*
76	* Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's session
77	* name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
78	* parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a session name
79	* was not set prior to this call.
80	*/
81	extern enum lttng_condition_status
82	lttng_condition_session_rotation_get_session_name(
83	const struct lttng_condition *condition,
84	const char **session_name);
85
86	/*
87	* Set the session name property of a session rotation condition.
88	*
89	* The passed session name parameter will be copied to the condition.
90	*
91	* Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
92	* if invalid paramenters are passed.
93	*/
94	extern enum lttng_condition_status
95	lttng_condition_session_rotation_set_session_name(
96	struct lttng_condition *condition,
97	const char *session_name);
98
99	/**
100	* lttng_evaluation_session_rotation are specialised lttng_evaluations
101	* which allow users to query a number of properties resulting from the
102	* evaluation of a condition which evaluated to true.
103	*/
104
105	/*
106	* Get the session rotation id property of a session rotation evaluation.
107	*
108	* Returns LTTNG_EVALUATION_STATUS_OK on success and the id of the session
109	* rotation, or LTTNG_EVALUATION_STATUS_INVALID if an invalid parameter is
110	* passed.
111	*/
112	extern enum lttng_evaluation_status
113	lttng_evaluation_session_rotation_get_id(
114	const struct lttng_evaluation evaluation, uint64_t id);
115
116	/*
117	* Get the session rotation location property of a session rotation completed
118	* evaluation.
119	*
120	* The caller does not assume the ownership of the returned location. The
121	* location shall only only be used for the duration of the evaluation's
122	* lifetime.
123	*
124	* Returns LTTNG_EVALUATION_STATUS_OK and set location on success.
125	* A NULL location may be returned if a rotation chunk's location
126	* has expired.
127	*
128	* LTTNG_EVALUATION_STATUS_INVALID is returned if an invalid parameter is
129	* passed.
130	*/
131	extern enum lttng_evaluation_status
132	lttng_evaluation_session_rotation_completed_get_location(
133	const struct lttng_evaluation *evaluation,
134	const struct lttng_trace_archive_location **location);
135
136	#ifdef __cplusplus
137	}
138	#endif
139
140	#endif /* LTTNG_CONDITION_SESSION_ROTATION_H */