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