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

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

#ifndef LTTNG_CONDITION_SESSION_ROTATION_H
#define LTTNG_CONDITION_SESSION_ROTATION_H

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

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