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

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

#ifndef LTTNG_ROTATION_H
#define LTTNG_ROTATION_H

#include <lttng/location.h>
#include <lttng/lttng-export.h>

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Return codes for lttng_rotation_handle_get_state()
 */
enum lttng_rotation_state {
	/*
	 * Session has not been rotated.
	 */
	LTTNG_ROTATION_STATE_NO_ROTATION = 0,
	/*
	 * Rotation is ongoing, but has not been completed yet.
	 */
	LTTNG_ROTATION_STATE_ONGOING = 1,
	/*
	 * Rotation has been completed and the resulting chunk
	 * can now safely be read.
	 */
	LTTNG_ROTATION_STATE_COMPLETED = 2,
	/*
	 * The rotation has expired.
	 *
	 * The information associated with a given rotation is eventually
	 * purged by the session daemon. In such a case, the attributes of
	 * the rotation, such as its path, may no longer be available.
	 *
	 * Note that this state does not guarantee the the rotation was
	 * completed successfully.
	 */
	LTTNG_ROTATION_STATE_EXPIRED = 3,
	/*
	 * The rotation could not be completed due to an error.
	 */
	LTTNG_ROTATION_STATE_ERROR = -1,
};

enum lttng_rotation_status {
	LTTNG_ROTATION_STATUS_OK = 0,
	/* Information not available. */
	LTTNG_ROTATION_STATUS_UNAVAILABLE = 1,
	/* Generic error. */
	LTTNG_ROTATION_STATUS_ERROR = -1,
	/* Invalid parameters provided. */
	LTTNG_ROTATION_STATUS_INVALID = -2,
	/* A schedule of this type is already set. */
	LTTNG_ROTATION_STATUS_SCHEDULE_ALREADY_SET = -3,
	/* No such rotation schedule set. */
	LTTNG_ROTATION_STATUS_SCHEDULE_NOT_SET = -3,
};

enum lttng_rotation_schedule_type {
	LTTNG_ROTATION_SCHEDULE_TYPE_UNKNOWN = -1,
	LTTNG_ROTATION_SCHEDULE_TYPE_SIZE_THRESHOLD = 0,
	LTTNG_ROTATION_SCHEDULE_TYPE_PERIODIC = 1,
};

/*
 * Descriptor of an immediate session rotation to be performed as soon as
 * possible by the tracers.
 */
struct lttng_rotation_immediate_descriptor;

/*
 * Session rotation schedule to add to a session.
 */
struct lttng_rotation_schedule;

/*
 * A set of lttng_rotation_schedule objects.
 */
struct lttng_rotation_schedules;

/*
 * Handle used to represent a specific rotation.
 */
struct lttng_rotation_handle;

/*
 * lttng rotate session handle functions.
 */

/*
 * Get the current state of the rotation referenced by the handle.
 *
 * This will issue a request to the session daemon on every call. Hence,
 * the result of this call may change over time.
 */
LTTNG_EXPORT extern enum lttng_rotation_status
lttng_rotation_handle_get_state(struct lttng_rotation_handle *rotation_handle,
				enum lttng_rotation_state *rotation_state);

/*
 * Get the location of the rotation's resulting archive.
 *
 * The rotation must be completed in order for this call to succeed.
 * The location returned remains owned by the rotation handle.
 *
 * Note that location will not be set in case of error, or if the session
 * rotation handle has expired.
 */
LTTNG_EXPORT extern enum lttng_rotation_status
lttng_rotation_handle_get_archive_location(struct lttng_rotation_handle *rotation_handle,
					   const struct lttng_trace_archive_location **location);

/*
 * Destroy an lttng_rotate_session handle.
 */
LTTNG_EXPORT extern void
lttng_rotation_handle_destroy(struct lttng_rotation_handle *rotation_handle);

/*
 * Rotate the output folder of the session.
 *
 * On success, handle is allocated and can be used to monitor the progress
 * of the rotation with lttng_rotation_get_state(). The handle must be freed
 * by the caller with lttng_rotation_handle_destroy().
 *
 * Passing NULL as the immediate rotation descriptor results in the default
 * options being used.
 *
 * Return 0 if the rotate action was successfully launched or a negative
 * LTTng error code on error.
 */
LTTNG_EXPORT extern int lttng_rotate_session(const char *session_name,
					     struct lttng_rotation_immediate_descriptor *descriptor,
					     struct lttng_rotation_handle **rotation_handle);

/*
 * Get the type of a rotation schedule object.
 */
LTTNG_EXPORT extern enum lttng_rotation_schedule_type
lttng_rotation_schedule_get_type(const struct lttng_rotation_schedule *schedule);

/*
 * Return a newly allocated size-based session rotation schedule or NULL on
 * error.
 */
LTTNG_EXPORT extern struct lttng_rotation_schedule *
lttng_rotation_schedule_size_threshold_create(void);

/*
 * Get a session rotation schedule's size threshold.
 *
 * Returns LTTNG_ROTATION_STATUS_OK on success.
 * LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset.
 */
LTTNG_EXPORT extern enum lttng_rotation_status
lttng_rotation_schedule_size_threshold_get_threshold(const struct lttng_rotation_schedule *schedule,
						     uint64_t *size_threshold_bytes);

/*
 * Set a session rotation schedule's size threshold.
 */
LTTNG_EXPORT extern enum lttng_rotation_status
lttng_rotation_schedule_size_threshold_set_threshold(struct lttng_rotation_schedule *schedule,
						     uint64_t size_threshold_bytes);

/*
 * Return a newly allocated periodic session rotation schedule or NULL on
 * error.
 */
LTTNG_EXPORT extern struct lttng_rotation_schedule *lttng_rotation_schedule_periodic_create(void);

/*
 * Get a time-based session rotation schedule's period.
 *
 * Returns LTTNG_ROTATION_STATUS_OK on success.
 * LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset.
 */
LTTNG_EXPORT extern enum lttng_rotation_status
lttng_rotation_schedule_periodic_get_period(const struct lttng_rotation_schedule *schedule,
					    uint64_t *period_us);

/*
 * Set a time-based session rotation schedule's period.
 */
LTTNG_EXPORT extern enum lttng_rotation_status
lttng_rotation_schedule_periodic_set_period(struct lttng_rotation_schedule *schedule,
					    uint64_t period_us);

/*
 * Destroy a rotation schedule.
 */
LTTNG_EXPORT extern void lttng_rotation_schedule_destroy(struct lttng_rotation_schedule *schedule);

/*
 * Destroy a set of rotation schedules. Pointers to any schedule contained
 * in this set become invalid after this call.
 */
LTTNG_EXPORT extern void
lttng_rotation_schedules_destroy(struct lttng_rotation_schedules *schedules);

/*
 * Get the number of schedules in a schedule set.
 */
LTTNG_EXPORT extern enum lttng_rotation_status
lttng_rotation_schedules_get_count(const struct lttng_rotation_schedules *schedules,
				   unsigned int *count);

/*
 * Get a schedule from the set at a given index.
 *
 * Note that the set maintains the ownership of the returned schedule.
 * It must not be destroyed by the user, nor should it be held beyond
 * the lifetime of the schedules set.
 *
 * Returns a rotation schedule, or NULL on error.
 */
LTTNG_EXPORT extern const struct lttng_rotation_schedule *
lttng_rotation_schedules_get_at_index(const struct lttng_rotation_schedules *schedules,
				      unsigned int index);

/*
 * Add a session rotation schedule to a session.
 *
 * Note that the current implementation currently limits the rotation schedules
 * associated to a given session to one per type.
 *
 * Returns LTTNG_ROTATION_STATUS_OK on success,
 * LTTNG_ROTATION_STATUS_SCHEDULE_ALREADY_SET if a rotation of the same type
 * is already set.
 */
LTTNG_EXPORT extern enum lttng_rotation_status
lttng_session_add_rotation_schedule(const char *session_name,
				    const struct lttng_rotation_schedule *schedule);

/*
 * Remove a session rotation schedule from a session.
 *
 * Returns LTTNG_ROTATION_STATUS_OK on success,
 * LTTNG_ROTATION_STATUS_SCHEDULE_INVALID if the provided schedule is
 * not set.
 */
LTTNG_EXPORT extern enum lttng_rotation_status
lttng_session_remove_rotation_schedule(const char *session_name,
				       const struct lttng_rotation_schedule *schedule);

/*
 * Get the rotation schedules associated with a given session.
 *
 * Returns LTTNG_OK on success, or a negative lttng error code on error.
 */
LTTNG_EXPORT extern int
lttng_session_list_rotation_schedules(const char *session_name,
				      struct lttng_rotation_schedules **schedules);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_ROTATION_H */
Commit	Line	Data
	1	/*
	2	* Copyright (C) 2017 Julien Desfossez <jdesfossez@efficios.com>
	3	* Copyright (C) 2018 Jérémie Galarneau <jeremie.galarneau@efficios.com>
	4	*
	5	* SPDX-License-Identifier: LGPL-2.1-only
	6	*
	7	*/
	8
	9	#ifndef LTTNG_ROTATION_H
	10	#define LTTNG_ROTATION_H
	11
	12	#include <lttng/location.h>
	13	#include <lttng/lttng-export.h>
	14
	15	#include <stdint.h>
	16
	17	#ifdef __cplusplus
	18	extern "C" {
	19	#endif
	20
	21	/*
	22	* Return codes for lttng_rotation_handle_get_state()
	23	*/
	24	enum lttng_rotation_state {
	25	/*
	26	* Session has not been rotated.
	27	*/
	28	LTTNG_ROTATION_STATE_NO_ROTATION = 0,
	29	/*
	30	* Rotation is ongoing, but has not been completed yet.
	31	*/
	32	LTTNG_ROTATION_STATE_ONGOING = 1,
	33	/*
	34	* Rotation has been completed and the resulting chunk
	35	* can now safely be read.
	36	*/
	37	LTTNG_ROTATION_STATE_COMPLETED = 2,
	38	/*
	39	* The rotation has expired.
	40	*
	41	* The information associated with a given rotation is eventually
	42	* purged by the session daemon. In such a case, the attributes of
	43	* the rotation, such as its path, may no longer be available.
	44	*
	45	* Note that this state does not guarantee the the rotation was
	46	* completed successfully.
	47	*/
	48	LTTNG_ROTATION_STATE_EXPIRED = 3,
	49	/*
	50	* The rotation could not be completed due to an error.
	51	*/
	52	LTTNG_ROTATION_STATE_ERROR = -1,
	53	};
	54
	55	enum lttng_rotation_status {
	56	LTTNG_ROTATION_STATUS_OK = 0,
	57	/* Information not available. */
	58	LTTNG_ROTATION_STATUS_UNAVAILABLE = 1,
	59	/* Generic error. */
	60	LTTNG_ROTATION_STATUS_ERROR = -1,
	61	/* Invalid parameters provided. */
	62	LTTNG_ROTATION_STATUS_INVALID = -2,
	63	/* A schedule of this type is already set. */
	64	LTTNG_ROTATION_STATUS_SCHEDULE_ALREADY_SET = -3,
	65	/* No such rotation schedule set. */
	66	LTTNG_ROTATION_STATUS_SCHEDULE_NOT_SET = -3,
	67	};
	68
	69	enum lttng_rotation_schedule_type {
	70	LTTNG_ROTATION_SCHEDULE_TYPE_UNKNOWN = -1,
	71	LTTNG_ROTATION_SCHEDULE_TYPE_SIZE_THRESHOLD = 0,
	72	LTTNG_ROTATION_SCHEDULE_TYPE_PERIODIC = 1,
	73	};
	74
	75	/*
	76	* Descriptor of an immediate session rotation to be performed as soon as
	77	* possible by the tracers.
	78	*/
	79	struct lttng_rotation_immediate_descriptor;
	80
	81	/*
	82	* Session rotation schedule to add to a session.
	83	*/
	84	struct lttng_rotation_schedule;
	85
	86	/*
	87	* A set of lttng_rotation_schedule objects.
	88	*/
	89	struct lttng_rotation_schedules;
	90
	91	/*
	92	* Handle used to represent a specific rotation.
	93	*/
	94	struct lttng_rotation_handle;
	95
	96	/*
	97	* lttng rotate session handle functions.
	98	*/
	99
	100	/*
	101	* Get the current state of the rotation referenced by the handle.
	102	*
	103	* This will issue a request to the session daemon on every call. Hence,
	104	* the result of this call may change over time.
	105	*/
	106	LTTNG_EXPORT extern enum lttng_rotation_status
	107	lttng_rotation_handle_get_state(struct lttng_rotation_handle *rotation_handle,
	108	enum lttng_rotation_state *rotation_state);
	109
	110	/*
	111	* Get the location of the rotation's resulting archive.
	112	*
	113	* The rotation must be completed in order for this call to succeed.
	114	* The location returned remains owned by the rotation handle.
	115	*
	116	* Note that location will not be set in case of error, or if the session
	117	* rotation handle has expired.
	118	*/
	119	LTTNG_EXPORT extern enum lttng_rotation_status
	120	lttng_rotation_handle_get_archive_location(struct lttng_rotation_handle *rotation_handle,
	121	const struct lttng_trace_archive_location **location);
	122
	123	/*
	124	* Destroy an lttng_rotate_session handle.
	125	*/
	126	LTTNG_EXPORT extern void
	127	lttng_rotation_handle_destroy(struct lttng_rotation_handle *rotation_handle);
	128
	129	/*
	130	* Rotate the output folder of the session.
	131	*
	132	* On success, handle is allocated and can be used to monitor the progress
	133	* of the rotation with lttng_rotation_get_state(). The handle must be freed
	134	* by the caller with lttng_rotation_handle_destroy().
	135	*
	136	* Passing NULL as the immediate rotation descriptor results in the default
	137	* options being used.
	138	*
	139	* Return 0 if the rotate action was successfully launched or a negative
	140	* LTTng error code on error.
	141	*/
	142	LTTNG_EXPORT extern int lttng_rotate_session(const char *session_name,
	143	struct lttng_rotation_immediate_descriptor *descriptor,
	144	struct lttng_rotation_handle **rotation_handle);
	145
	146	/*
	147	* Get the type of a rotation schedule object.
	148	*/
	149	LTTNG_EXPORT extern enum lttng_rotation_schedule_type
	150	lttng_rotation_schedule_get_type(const struct lttng_rotation_schedule *schedule);
	151
	152	/*
	153	* Return a newly allocated size-based session rotation schedule or NULL on
	154	* error.
	155	*/
	156	LTTNG_EXPORT extern struct lttng_rotation_schedule *
	157	lttng_rotation_schedule_size_threshold_create(void);
	158
	159	/*
	160	* Get a session rotation schedule's size threshold.
	161	*
	162	* Returns LTTNG_ROTATION_STATUS_OK on success.
	163	* LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset.
	164	*/
	165	LTTNG_EXPORT extern enum lttng_rotation_status
	166	lttng_rotation_schedule_size_threshold_get_threshold(const struct lttng_rotation_schedule *schedule,
	167	uint64_t *size_threshold_bytes);
	168
	169	/*
	170	* Set a session rotation schedule's size threshold.
	171	*/
	172	LTTNG_EXPORT extern enum lttng_rotation_status
	173	lttng_rotation_schedule_size_threshold_set_threshold(struct lttng_rotation_schedule *schedule,
	174	uint64_t size_threshold_bytes);
	175
	176	/*
	177	* Return a newly allocated periodic session rotation schedule or NULL on
	178	* error.
	179	*/
	180	LTTNG_EXPORT extern struct lttng_rotation_schedule *lttng_rotation_schedule_periodic_create(void);
	181
	182	/*
	183	* Get a time-based session rotation schedule's period.
	184	*
	185	* Returns LTTNG_ROTATION_STATUS_OK on success.
	186	* LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset.
	187	*/
	188	LTTNG_EXPORT extern enum lttng_rotation_status
	189	lttng_rotation_schedule_periodic_get_period(const struct lttng_rotation_schedule *schedule,
	190	uint64_t *period_us);
	191
	192	/*
	193	* Set a time-based session rotation schedule's period.
	194	*/
	195	LTTNG_EXPORT extern enum lttng_rotation_status
	196	lttng_rotation_schedule_periodic_set_period(struct lttng_rotation_schedule *schedule,
	197	uint64_t period_us);
	198
	199	/*
	200	* Destroy a rotation schedule.
	201	*/
	202	LTTNG_EXPORT extern void lttng_rotation_schedule_destroy(struct lttng_rotation_schedule *schedule);
	203
	204	/*
	205	* Destroy a set of rotation schedules. Pointers to any schedule contained
	206	* in this set become invalid after this call.
	207	*/
	208	LTTNG_EXPORT extern void
	209	lttng_rotation_schedules_destroy(struct lttng_rotation_schedules *schedules);
	210
	211	/*
	212	* Get the number of schedules in a schedule set.
	213	*/
	214	LTTNG_EXPORT extern enum lttng_rotation_status
	215	lttng_rotation_schedules_get_count(const struct lttng_rotation_schedules *schedules,
	216	unsigned int *count);
	217
	218	/*
	219	* Get a schedule from the set at a given index.
	220	*
	221	* Note that the set maintains the ownership of the returned schedule.
	222	* It must not be destroyed by the user, nor should it be held beyond
	223	* the lifetime of the schedules set.
	224	*
	225	* Returns a rotation schedule, or NULL on error.
	226	*/
	227	LTTNG_EXPORT extern const struct lttng_rotation_schedule *
	228	lttng_rotation_schedules_get_at_index(const struct lttng_rotation_schedules *schedules,
	229	unsigned int index);
	230
	231	/*
	232	* Add a session rotation schedule to a session.
	233	*
	234	* Note that the current implementation currently limits the rotation schedules
	235	* associated to a given session to one per type.
	236	*
	237	* Returns LTTNG_ROTATION_STATUS_OK on success,
	238	* LTTNG_ROTATION_STATUS_SCHEDULE_ALREADY_SET if a rotation of the same type
	239	* is already set.
	240	*/
	241	LTTNG_EXPORT extern enum lttng_rotation_status
	242	lttng_session_add_rotation_schedule(const char *session_name,
	243	const struct lttng_rotation_schedule *schedule);
	244
	245	/*
	246	* Remove a session rotation schedule from a session.
	247	*
	248	* Returns LTTNG_ROTATION_STATUS_OK on success,
	249	* LTTNG_ROTATION_STATUS_SCHEDULE_INVALID if the provided schedule is
	250	* not set.
	251	*/
	252	LTTNG_EXPORT extern enum lttng_rotation_status
	253	lttng_session_remove_rotation_schedule(const char *session_name,
	254	const struct lttng_rotation_schedule *schedule);
	255
	256	/*
	257	* Get the rotation schedules associated with a given session.
	258	*
	259	* Returns LTTNG_OK on success, or a negative lttng error code on error.
	260	*/
	261	LTTNG_EXPORT extern int
	262	lttng_session_list_rotation_schedules(const char *session_name,
	263	struct lttng_rotation_schedules **schedules);
	264
	265	#ifdef __cplusplus
	266	}
	267	#endif
	268
	269	#endif /* LTTNG_ROTATION_H */