Move to kernel style SPDX license identifiers
[lttng-tools.git] / include / lttng / rotation.h
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 <stdint.h>
13 #include <lttng/location.h>
14
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18
19 /*
20 * Return codes for lttng_rotation_handle_get_state()
21 */
22 enum lttng_rotation_state {
23 /*
24 * Session has not been rotated.
25 */
26 LTTNG_ROTATION_STATE_NO_ROTATION = 0,
27 /*
28 * Rotation is ongoing, but has not been completed yet.
29 */
30 LTTNG_ROTATION_STATE_ONGOING = 1,
31 /*
32 * Rotation has been completed and the resulting chunk
33 * can now safely be read.
34 */
35 LTTNG_ROTATION_STATE_COMPLETED = 2,
36 /*
37 * The rotation has expired.
38 *
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.
42 *
43 * Note that this state does not guarantee the the rotation was
44 * completed successfully.
45 */
46 LTTNG_ROTATION_STATE_EXPIRED = 3,
47 /*
48 * The rotation could not be completed due to an error.
49 */
50 LTTNG_ROTATION_STATE_ERROR = -1,
51 };
52
53 enum lttng_rotation_status {
54 LTTNG_ROTATION_STATUS_OK = 0,
55 /* Information not available. */
56 LTTNG_ROTATION_STATUS_UNAVAILABLE = 1,
57 /* Generic error. */
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,
65 };
66
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,
71 };
72
73 /*
74 * Descriptor of an immediate session rotation to be performed as soon as
75 * possible by the tracers.
76 */
77 struct lttng_rotation_immediate_descriptor;
78
79 /*
80 * Session rotation schedule to add to a session.
81 */
82 struct lttng_rotation_schedule;
83
84 /*
85 * A set of lttng_rotation_schedule objects.
86 */
87 struct lttng_rotation_schedules;
88
89 /*
90 * Handle used to represent a specific rotation.
91 */
92 struct lttng_rotation_handle;
93
94 /*
95 * lttng rotate session handle functions.
96 */
97
98 /*
99 * Get the current state of the rotation referenced by the handle.
100 *
101 * This will issue a request to the session daemon on every call. Hence,
102 * the result of this call may change over time.
103 */
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);
107
108 /*
109 * Get the location of the rotation's resulting archive.
110 *
111 * The rotation must be completed in order for this call to succeed.
112 * The location returned remains owned by the rotation handle.
113 *
114 * Note that location will not be set in case of error, or if the session
115 * rotation handle has expired.
116 */
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);
120
121 /*
122 * Destroy an lttng_rotate_session handle.
123 */
124 extern void lttng_rotation_handle_destroy(
125 struct lttng_rotation_handle *rotation_handle);
126
127 /*
128 * Rotate the output folder of the session.
129 *
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().
133 *
134 * Passing NULL as the immediate rotation descriptor results in the default
135 * options being used.
136 *
137 * Return 0 if the rotate action was successfully launched or a negative
138 * LTTng error code on error.
139 */
140 extern int lttng_rotate_session(const char *session_name,
141 struct lttng_rotation_immediate_descriptor *descriptor,
142 struct lttng_rotation_handle **rotation_handle);
143
144 /*
145 * Get the type of a rotation schedule object.
146 */
147 extern enum lttng_rotation_schedule_type lttng_rotation_schedule_get_type(
148 const struct lttng_rotation_schedule *schedule);
149
150 /*
151 * Return a newly allocated size-based session rotation schedule or NULL on
152 * error.
153 */
154 extern struct lttng_rotation_schedule *
155 lttng_rotation_schedule_size_threshold_create(void);
156
157 /*
158 * Get a session rotation schedule's size threshold.
159 *
160 * Returns LTTNG_ROTATION_STATUS_OK on success.
161 * LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset.
162 */
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);
167
168 /*
169 * Set a session rotation schedule's size threshold.
170 */
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);
175
176 /*
177 * Return a newly allocated periodic session rotation schedule or NULL on
178 * error.
179 */
180 extern struct lttng_rotation_schedule *
181 lttng_rotation_schedule_periodic_create(void);
182
183 /*
184 * Get a time-based session rotation schedule's period.
185 *
186 * Returns LTTNG_ROTATION_STATUS_OK on success.
187 * LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset.
188 */
189 extern enum lttng_rotation_status lttng_rotation_schedule_periodic_get_period(
190 const struct lttng_rotation_schedule *schedule,
191 uint64_t *period_us);
192
193 /*
194 * Set a time-based session rotation schedule's period.
195 */
196 extern enum lttng_rotation_status lttng_rotation_schedule_periodic_set_period(
197 struct lttng_rotation_schedule *schedule,
198 uint64_t period_us);
199
200 /*
201 * Destroy a rotation schedule.
202 */
203 extern void lttng_rotation_schedule_destroy(
204 struct lttng_rotation_schedule *schedule);
205
206 /*
207 * Destroy a set of rotation schedules. Pointers to any schedule contained
208 * in this set become invalid after this call.
209 */
210 extern void lttng_rotation_schedules_destroy(
211 struct lttng_rotation_schedules *schedules);
212
213 /*
214 * Get the number of schedules in a schedule set.
215 */
216 extern enum lttng_rotation_status lttng_rotation_schedules_get_count(
217 const struct lttng_rotation_schedules *schedules,
218 unsigned int *count);
219
220 /*
221 * Get a schedule from the set at a given index.
222 *
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.
226 *
227 * Returns a rotation schedule, or NULL on error.
228 */
229 extern const struct lttng_rotation_schedule *
230 lttng_rotation_schedules_get_at_index(
231 const struct lttng_rotation_schedules *schedules,
232 unsigned int index);
233
234 /*
235 * Add a session rotation schedule to a session.
236 *
237 * Note that the current implementation currently limits the rotation schedules
238 * associated to a given session to one per type.
239 *
240 * Returns LTTNG_ROTATION_STATUS_OK on success,
241 * LTTNG_ROTATION_STATUS_SCHEDULE_ALREADY_SET if a rotation of the same type
242 * is already set.
243 */
244 extern enum lttng_rotation_status lttng_session_add_rotation_schedule(
245 const char *session_name,
246 const struct lttng_rotation_schedule *schedule);
247
248 /*
249 * Remove a session rotation schedule from a session.
250 *
251 * Returns LTTNG_ROTATION_STATUS_OK on success,
252 * LTTNG_ROTATION_STATUS_SCHEDULE_INVALID if the provided schedule is
253 * not set.
254 */
255 extern enum lttng_rotation_status lttng_session_remove_rotation_schedule(
256 const char *session_name,
257 const struct lttng_rotation_schedule *schedule);
258
259 /*
260 * Get the rotation schedules associated with a given session.
261 *
262 * Returns LTTNG_OK on success, or a negative lttng error code on error.
263 */
264 extern int lttng_session_list_rotation_schedules(
265 const char *session_name,
266 struct lttng_rotation_schedules **schedules);
267
268 #ifdef __cplusplus
269 }
270 #endif
271
272 #endif /* LTTNG_ROTATION_H */
This page took 0.052326 seconds and 5 git commands to generate.