0b4b2ad2f5eb8f92c01e60f9a484e8d23c3b19fd
[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
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27
28 /*
29 * Return codes for lttng_rotation_handle_get_state()
30 */
31 enum lttng_rotation_state {
32 /*
33 * Session has not been rotated.
34 */
35 LTTNG_ROTATION_STATE_NO_ROTATION = 0,
36 /*
37 * Rotation is ongoing, but has not been completed yet.
38 */
39 LTTNG_ROTATION_STATE_ONGOING = 1,
40 /*
41 * Rotation has been completed and the resulting chunk
42 * can now safely be read.
43 */
44 LTTNG_ROTATION_STATE_COMPLETED = 2,
45 /*
46 * The rotation has expired.
47 *
48 * The information associated with a given rotation is eventually
49 * purged by the session daemon. In such a case, the attributes of
50 * the rotation, such as its path, may no longer be available.
51 *
52 * Note that this state does not guarantee the the rotation was
53 * completed successfully.
54 */
55 LTTNG_ROTATION_STATE_EXPIRED = 3,
56 /*
57 * The rotation could not be completed due to an error.
58 */
59 LTTNG_ROTATION_STATE_ERROR = 4,
60 };
61
62 enum lttng_rotation_status {
63 LTTNG_ROTATION_STATUS_OK = 0,
64 /* Information not available. */
65 LTTNG_ROTATION_STATUS_UNAVAILABLE = 1,
66 /* Generic error. */
67 LTTNG_ROTATION_STATUS_ERROR = -1,
68 /* Invalid parameters provided. */
69 LTTNG_ROTATION_STATUS_INVALID = -2,
70 };
71
72 /*
73 * Input parameter to the lttng_rotate_session command.
74 *
75 * An immediate rotation is performed as soon as possible by the tracers.
76 */
77 struct lttng_rotation_immediate_attr;
78
79 /*
80 * Input parameter to the lttng_rotate_schedule command.
81 */
82 struct lttng_rotation_schedule_attr;
83
84 /*
85 * Handle used to represent a specific rotation.
86 */
87 struct lttng_rotation_handle;
88
89 /*
90 * Return a newly allocated immediate session rotation descriptor object or NULL
91 * on error.
92 */
93 extern struct lttng_rotation_immediate_attr *
94 lttng_rotation_immediate_attr_create(void);
95
96 /*
97 * Return a newly allocated scheduled rotate session descriptor object or NULL
98 * on error.
99 */
100 extern struct lttng_rotation_schedule_attr *
101 lttng_rotation_schedule_attr_create(void);
102
103 /*
104 * Destroy a given immediate session rotation descriptor object.
105 */
106 extern void lttng_rotation_immediate_attr_destroy(
107 struct lttng_rotation_immediate_attr *attr);
108
109 /*
110 * Destroy a given scheduled rotate session descriptor object.
111 */
112 extern void lttng_rotation_schedule_attr_destroy(
113 struct lttng_rotation_schedule_attr *attr);
114
115 /*
116 * Set the name of the session to rotate immediately.
117 *
118 * The session_name parameter is copied to the immediate session rotation
119 * attributes.
120 */
121 extern enum lttng_rotation_status lttng_rotation_immediate_attr_set_session_name(
122 struct lttng_rotation_immediate_attr *attr,
123 const char *session_name);
124
125 /*
126 * Set the name of the session to rotate automatically.
127 *
128 * The session_name parameter is copied to the immediate session rotation
129 * attributes.
130 */
131 extern enum lttng_rotation_status lttng_rotation_schedule_attr_set_session_name(
132 struct lttng_rotation_schedule_attr *attr,
133 const char *session_name);
134
135 /*
136 * Set the timer to periodically rotate the session (µs, -1ULL to disable).
137 */
138 extern enum lttng_rotation_status lttng_rotation_schedule_attr_set_timer_period(
139 struct lttng_rotation_schedule_attr *attr, uint64_t timer);
140
141 /*
142 * Set the size to rotate the session (bytes, -1ULL to disable).
143 */
144 void lttng_rotation_schedule_attr_set_size(
145 struct lttng_rotation_schedule_attr *attr, uint64_t size);
146
147 /*
148 * lttng rotate session handle functions.
149 */
150
151 /*
152 * Get the current state of the rotation referenced by the handle.
153 *
154 * This will issue a request to the session daemon on every call. Hence,
155 * the result of this call may change over time.
156 */
157 extern enum lttng_rotation_status lttng_rotation_handle_get_state(
158 struct lttng_rotation_handle *rotation_handle,
159 enum lttng_rotation_state *rotation_state);
160
161 /*
162 * Get the location of the rotation's resulting archive.
163 *
164 * The rotation must be completed in order for this call to succeed.
165 * The path returned is owned by the rotation handle.
166 *
167 * Note that path will not be set in case of error, or if the session
168 * rotation has expired.
169 *
170 * FIXME: Return an lttng_location object instead of a path.
171 */
172 extern enum lttng_rotation_status lttng_rotation_handle_get_completed_archive_location(
173 struct lttng_rotation_handle *rotation_handle,
174 const char **path);
175
176 /*
177 * Destroy an lttng_rotate_session handle.
178 */
179 extern void lttng_rotation_handle_destroy(
180 struct lttng_rotation_handle *rotation_handle);
181
182 /*
183 * Rotate the output folder of the session
184 *
185 * On success, handle is allocated and can be used to monitor the progress
186 * of the rotation with lttng_rotation_get_state(). The handle must be freed
187 * by the caller with lttng_rotation_handle_destroy().
188 *
189 * Return 0 if the rotate action was successfully launched or a negative
190 * LTTng error code on error.
191 */
192 extern int lttng_rotate_session(struct lttng_rotation_immediate_attr *attr,
193 struct lttng_rotation_handle **rotation_handle);
194
195 /*
196 * Configure a session to rotate periodically or based on the size written.
197 */
198 extern int lttng_rotation_set_schedule(
199 struct lttng_rotation_schedule_attr *attr);
200
201 /*
202 * Ask the sessiond for the value of the rotate timer (in micro-seconds) of the
203 * session.
204 *
205 * On success, return 0 and set the value or rotate_timer, on error return a
206 * negative value.
207 */
208 extern int lttng_rotation_schedule_get_timer_period(const char *session_name,
209 uint64_t *rotate_timer);
210
211 /*
212 * Ask the sessiond for the value of the rotate size (in micro-seconds) of the
213 * session.
214 *
215 * On success, return 0 and set the value or rotate_size, on error return
216 * a negative value.
217 */
218 extern int lttng_rotation_schedule_get_size(const char *session_name,
219 uint64_t *rotate_size);
220
221 #ifdef __cplusplus
222 }
223 #endif
224
225 #endif /* LTTNG_ROTATION_H */
This page took 0.067222 seconds and 4 git commands to generate.