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>
20 * Return codes for lttng_rotation_handle_get_state()
22 enum lttng_rotation_state
{
24 * Session has not been rotated.
26 LTTNG_ROTATION_STATE_NO_ROTATION
= 0,
28 * Rotation is ongoing, but has not been completed yet.
30 LTTNG_ROTATION_STATE_ONGOING
= 1,
32 * Rotation has been completed and the resulting chunk
33 * can now safely be read.
35 LTTNG_ROTATION_STATE_COMPLETED
= 2,
37 * The rotation has expired.
39 * The information associated with a given rotation is eventually
40 * purged by the session daemon. In such a case, the attributes of
41 * the rotation, such as its path, may no longer be available.
43 * Note that this state does not guarantee the the rotation was
44 * completed successfully.
46 LTTNG_ROTATION_STATE_EXPIRED
= 3,
48 * The rotation could not be completed due to an error.
50 LTTNG_ROTATION_STATE_ERROR
= -1,
53 enum lttng_rotation_status
{
54 LTTNG_ROTATION_STATUS_OK
= 0,
55 /* Information not available. */
56 LTTNG_ROTATION_STATUS_UNAVAILABLE
= 1,
58 LTTNG_ROTATION_STATUS_ERROR
= -1,
59 /* Invalid parameters provided. */
60 LTTNG_ROTATION_STATUS_INVALID
= -2,
61 /* A schedule of this type is already set. */
62 LTTNG_ROTATION_STATUS_SCHEDULE_ALREADY_SET
= -3,
63 /* No such rotation schedule set. */
64 LTTNG_ROTATION_STATUS_SCHEDULE_NOT_SET
= -3,
67 enum lttng_rotation_schedule_type
{
68 LTTNG_ROTATION_SCHEDULE_TYPE_UNKNOWN
= -1,
69 LTTNG_ROTATION_SCHEDULE_TYPE_SIZE_THRESHOLD
= 0,
70 LTTNG_ROTATION_SCHEDULE_TYPE_PERIODIC
= 1,
74 * Descriptor of an immediate session rotation to be performed as soon as
75 * possible by the tracers.
77 struct lttng_rotation_immediate_descriptor
;
80 * Session rotation schedule to add to a session.
82 struct lttng_rotation_schedule
;
85 * A set of lttng_rotation_schedule objects.
87 struct lttng_rotation_schedules
;
90 * Handle used to represent a specific rotation.
92 struct lttng_rotation_handle
;
95 * lttng rotate session handle functions.
99 * Get the current state of the rotation referenced by the handle.
101 * This will issue a request to the session daemon on every call. Hence,
102 * the result of this call may change over time.
104 extern enum lttng_rotation_status
lttng_rotation_handle_get_state(
105 struct lttng_rotation_handle
*rotation_handle
,
106 enum lttng_rotation_state
*rotation_state
);
109 * Get the location of the rotation's resulting archive.
111 * The rotation must be completed in order for this call to succeed.
112 * The location returned remains owned by the rotation handle.
114 * Note that location will not be set in case of error, or if the session
115 * rotation handle has expired.
117 extern enum lttng_rotation_status
lttng_rotation_handle_get_archive_location(
118 struct lttng_rotation_handle
*rotation_handle
,
119 const struct lttng_trace_archive_location
**location
);
122 * Destroy an lttng_rotate_session handle.
124 extern void lttng_rotation_handle_destroy(
125 struct lttng_rotation_handle
*rotation_handle
);
128 * Rotate the output folder of the session.
130 * On success, handle is allocated and can be used to monitor the progress
131 * of the rotation with lttng_rotation_get_state(). The handle must be freed
132 * by the caller with lttng_rotation_handle_destroy().
134 * Passing NULL as the immediate rotation descriptor results in the default
135 * options being used.
137 * Return 0 if the rotate action was successfully launched or a negative
138 * LTTng error code on error.
140 extern int lttng_rotate_session(const char *session_name
,
141 struct lttng_rotation_immediate_descriptor
*descriptor
,
142 struct lttng_rotation_handle
**rotation_handle
);
145 * Get the type of a rotation schedule object.
147 extern enum lttng_rotation_schedule_type
lttng_rotation_schedule_get_type(
148 const struct lttng_rotation_schedule
*schedule
);
151 * Return a newly allocated size-based session rotation schedule or NULL on
154 extern struct lttng_rotation_schedule
*
155 lttng_rotation_schedule_size_threshold_create(void);
158 * Get a session rotation schedule's size threshold.
160 * Returns LTTNG_ROTATION_STATUS_OK on success.
161 * LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset.
163 extern enum lttng_rotation_status
164 lttng_rotation_schedule_size_threshold_get_threshold(
165 const struct lttng_rotation_schedule
*schedule
,
166 uint64_t *size_threshold_bytes
);
169 * Set a session rotation schedule's size threshold.
171 extern enum lttng_rotation_status
172 lttng_rotation_schedule_size_threshold_set_threshold(
173 struct lttng_rotation_schedule
*schedule
,
174 uint64_t size_threshold_bytes
);
177 * Return a newly allocated periodic session rotation schedule or NULL on
180 extern struct lttng_rotation_schedule
*
181 lttng_rotation_schedule_periodic_create(void);
184 * Get a time-based session rotation schedule's period.
186 * Returns LTTNG_ROTATION_STATUS_OK on success.
187 * LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset.
189 extern enum lttng_rotation_status
lttng_rotation_schedule_periodic_get_period(
190 const struct lttng_rotation_schedule
*schedule
,
191 uint64_t *period_us
);
194 * Set a time-based session rotation schedule's period.
196 extern enum lttng_rotation_status
lttng_rotation_schedule_periodic_set_period(
197 struct lttng_rotation_schedule
*schedule
,
201 * Destroy a rotation schedule.
203 extern void lttng_rotation_schedule_destroy(
204 struct lttng_rotation_schedule
*schedule
);
207 * Destroy a set of rotation schedules. Pointers to any schedule contained
208 * in this set become invalid after this call.
210 extern void lttng_rotation_schedules_destroy(
211 struct lttng_rotation_schedules
*schedules
);
214 * Get the number of schedules in a schedule set.
216 extern enum lttng_rotation_status
lttng_rotation_schedules_get_count(
217 const struct lttng_rotation_schedules
*schedules
,
218 unsigned int *count
);
221 * Get a schedule from the set at a given index.
223 * Note that the set maintains the ownership of the returned schedule.
224 * It must not be destroyed by the user, nor should it be held beyond
225 * the lifetime of the schedules set.
227 * Returns a rotation schedule, or NULL on error.
229 extern const struct lttng_rotation_schedule
*
230 lttng_rotation_schedules_get_at_index(
231 const struct lttng_rotation_schedules
*schedules
,
235 * Add a session rotation schedule to a session.
237 * Note that the current implementation currently limits the rotation schedules
238 * associated to a given session to one per type.
240 * Returns LTTNG_ROTATION_STATUS_OK on success,
241 * LTTNG_ROTATION_STATUS_SCHEDULE_ALREADY_SET if a rotation of the same type
244 extern enum lttng_rotation_status
lttng_session_add_rotation_schedule(
245 const char *session_name
,
246 const struct lttng_rotation_schedule
*schedule
);
249 * Remove a session rotation schedule from a session.
251 * Returns LTTNG_ROTATION_STATUS_OK on success,
252 * LTTNG_ROTATION_STATUS_SCHEDULE_INVALID if the provided schedule is
255 extern enum lttng_rotation_status
lttng_session_remove_rotation_schedule(
256 const char *session_name
,
257 const struct lttng_rotation_schedule
*schedule
);
260 * Get the rotation schedules associated with a given session.
262 * Returns LTTNG_OK on success, or a negative lttng error code on error.
264 extern int lttng_session_list_rotation_schedules(
265 const char *session_name
,
266 struct lttng_rotation_schedules
**schedules
);
272 #endif /* LTTNG_ROTATION_H */