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