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