2 * Copyright (C) 2017 Julien Desfossez <jdesfossez@efficios.com>
3 * Copyright (C) 2018 Jérémie Galarneau <jeremie.galarneau@efficios.com>
5 * SPDX-License-Identifier: LGPL-2.1-only
9 #ifndef LTTNG_ROTATION_H
10 #define LTTNG_ROTATION_H
13 #include <lttng/location.h>
14 #include <lttng/lttng-export.h>
21 * Return codes for lttng_rotation_handle_get_state()
23 enum lttng_rotation_state
{
25 * Session has not been rotated.
27 LTTNG_ROTATION_STATE_NO_ROTATION
= 0,
29 * Rotation is ongoing, but has not been completed yet.
31 LTTNG_ROTATION_STATE_ONGOING
= 1,
33 * Rotation has been completed and the resulting chunk
34 * can now safely be read.
36 LTTNG_ROTATION_STATE_COMPLETED
= 2,
38 * The rotation has expired.
40 * The information associated with a given rotation is eventually
41 * purged by the session daemon. In such a case, the attributes of
42 * the rotation, such as its path, may no longer be available.
44 * Note that this state does not guarantee the the rotation was
45 * completed successfully.
47 LTTNG_ROTATION_STATE_EXPIRED
= 3,
49 * The rotation could not be completed due to an error.
51 LTTNG_ROTATION_STATE_ERROR
= -1,
54 enum lttng_rotation_status
{
55 LTTNG_ROTATION_STATUS_OK
= 0,
56 /* Information not available. */
57 LTTNG_ROTATION_STATUS_UNAVAILABLE
= 1,
59 LTTNG_ROTATION_STATUS_ERROR
= -1,
60 /* Invalid parameters provided. */
61 LTTNG_ROTATION_STATUS_INVALID
= -2,
62 /* A schedule of this type is already set. */
63 LTTNG_ROTATION_STATUS_SCHEDULE_ALREADY_SET
= -3,
64 /* No such rotation schedule set. */
65 LTTNG_ROTATION_STATUS_SCHEDULE_NOT_SET
= -3,
68 enum lttng_rotation_schedule_type
{
69 LTTNG_ROTATION_SCHEDULE_TYPE_UNKNOWN
= -1,
70 LTTNG_ROTATION_SCHEDULE_TYPE_SIZE_THRESHOLD
= 0,
71 LTTNG_ROTATION_SCHEDULE_TYPE_PERIODIC
= 1,
75 * Descriptor of an immediate session rotation to be performed as soon as
76 * possible by the tracers.
78 struct lttng_rotation_immediate_descriptor
;
81 * Session rotation schedule to add to a session.
83 struct lttng_rotation_schedule
;
86 * A set of lttng_rotation_schedule objects.
88 struct lttng_rotation_schedules
;
91 * Handle used to represent a specific rotation.
93 struct lttng_rotation_handle
;
96 * lttng rotate session handle functions.
100 * Get the current state of the rotation referenced by the handle.
102 * This will issue a request to the session daemon on every call. Hence,
103 * the result of this call may change over time.
105 LTTNG_EXPORT
extern enum lttng_rotation_status
lttng_rotation_handle_get_state(
106 struct lttng_rotation_handle
*rotation_handle
,
107 enum lttng_rotation_state
*rotation_state
);
110 * Get the location of the rotation's resulting archive.
112 * The rotation must be completed in order for this call to succeed.
113 * The location returned remains owned by the rotation handle.
115 * Note that location will not be set in case of error, or if the session
116 * rotation handle has expired.
118 LTTNG_EXPORT
extern enum lttng_rotation_status
lttng_rotation_handle_get_archive_location(
119 struct lttng_rotation_handle
*rotation_handle
,
120 const struct lttng_trace_archive_location
**location
);
123 * Destroy an lttng_rotate_session handle.
125 LTTNG_EXPORT
extern void lttng_rotation_handle_destroy(
126 struct lttng_rotation_handle
*rotation_handle
);
129 * Rotate the output folder of the session.
131 * On success, handle is allocated and can be used to monitor the progress
132 * of the rotation with lttng_rotation_get_state(). The handle must be freed
133 * by the caller with lttng_rotation_handle_destroy().
135 * Passing NULL as the immediate rotation descriptor results in the default
136 * options being used.
138 * Return 0 if the rotate action was successfully launched or a negative
139 * LTTng error code on error.
141 LTTNG_EXPORT
extern int lttng_rotate_session(const char *session_name
,
142 struct lttng_rotation_immediate_descriptor
*descriptor
,
143 struct lttng_rotation_handle
**rotation_handle
);
146 * Get the type of a rotation schedule object.
148 LTTNG_EXPORT
extern enum lttng_rotation_schedule_type
lttng_rotation_schedule_get_type(
149 const struct lttng_rotation_schedule
*schedule
);
152 * Return a newly allocated size-based session rotation schedule or NULL on
155 LTTNG_EXPORT
extern struct lttng_rotation_schedule
*
156 lttng_rotation_schedule_size_threshold_create(void);
159 * Get a session rotation schedule's size threshold.
161 * Returns LTTNG_ROTATION_STATUS_OK on success.
162 * LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset.
164 LTTNG_EXPORT
extern enum lttng_rotation_status
165 lttng_rotation_schedule_size_threshold_get_threshold(
166 const struct lttng_rotation_schedule
*schedule
,
167 uint64_t *size_threshold_bytes
);
170 * Set a session rotation schedule's size threshold.
172 LTTNG_EXPORT
extern enum lttng_rotation_status
173 lttng_rotation_schedule_size_threshold_set_threshold(
174 struct lttng_rotation_schedule
*schedule
,
175 uint64_t size_threshold_bytes
);
178 * Return a newly allocated periodic session rotation schedule or NULL on
181 LTTNG_EXPORT
extern struct lttng_rotation_schedule
*
182 lttng_rotation_schedule_periodic_create(void);
185 * Get a time-based session rotation schedule's period.
187 * Returns LTTNG_ROTATION_STATUS_OK on success.
188 * LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset.
190 LTTNG_EXPORT
extern enum lttng_rotation_status
lttng_rotation_schedule_periodic_get_period(
191 const struct lttng_rotation_schedule
*schedule
,
192 uint64_t *period_us
);
195 * Set a time-based session rotation schedule's period.
197 LTTNG_EXPORT
extern enum lttng_rotation_status
lttng_rotation_schedule_periodic_set_period(
198 struct lttng_rotation_schedule
*schedule
,
202 * Destroy a rotation schedule.
204 LTTNG_EXPORT
extern void lttng_rotation_schedule_destroy(
205 struct lttng_rotation_schedule
*schedule
);
208 * Destroy a set of rotation schedules. Pointers to any schedule contained
209 * in this set become invalid after this call.
211 LTTNG_EXPORT
extern void lttng_rotation_schedules_destroy(
212 struct lttng_rotation_schedules
*schedules
);
215 * Get the number of schedules in a schedule set.
217 LTTNG_EXPORT
extern enum lttng_rotation_status
lttng_rotation_schedules_get_count(
218 const struct lttng_rotation_schedules
*schedules
,
219 unsigned int *count
);
222 * Get a schedule from the set at a given index.
224 * Note that the set maintains the ownership of the returned schedule.
225 * It must not be destroyed by the user, nor should it be held beyond
226 * the lifetime of the schedules set.
228 * Returns a rotation schedule, or NULL on error.
230 LTTNG_EXPORT
extern const struct lttng_rotation_schedule
*
231 lttng_rotation_schedules_get_at_index(
232 const struct lttng_rotation_schedules
*schedules
,
236 * Add a session rotation schedule to a session.
238 * Note that the current implementation currently limits the rotation schedules
239 * associated to a given session to one per type.
241 * Returns LTTNG_ROTATION_STATUS_OK on success,
242 * LTTNG_ROTATION_STATUS_SCHEDULE_ALREADY_SET if a rotation of the same type
245 LTTNG_EXPORT
extern enum lttng_rotation_status
lttng_session_add_rotation_schedule(
246 const char *session_name
,
247 const struct lttng_rotation_schedule
*schedule
);
250 * Remove a session rotation schedule from a session.
252 * Returns LTTNG_ROTATION_STATUS_OK on success,
253 * LTTNG_ROTATION_STATUS_SCHEDULE_INVALID if the provided schedule is
256 LTTNG_EXPORT
extern enum lttng_rotation_status
lttng_session_remove_rotation_schedule(
257 const char *session_name
,
258 const struct lttng_rotation_schedule
*schedule
);
261 * Get the rotation schedules associated with a given session.
263 * Returns LTTNG_OK on success, or a negative lttng error code on error.
265 LTTNG_EXPORT
extern int lttng_session_list_rotation_schedules(
266 const char *session_name
,
267 struct lttng_rotation_schedules
**schedules
);
273 #endif /* LTTNG_ROTATION_H */