2 * Copyright (C) 2017 - Julien Desfossez <jdesfossez@efficios.com>
3 * Copyright (C) 2018 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
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.
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
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
19 #ifndef LTTNG_ROTATION_H
20 #define LTTNG_ROTATION_H
23 #include <lttng/location.h>
30 * Return codes for lttng_rotation_handle_get_state()
32 enum lttng_rotation_state
{
34 * Session has not been rotated.
36 LTTNG_ROTATION_STATE_NO_ROTATION
= 0,
38 * Rotation is ongoing, but has not been completed yet.
40 LTTNG_ROTATION_STATE_ONGOING
= 1,
42 * Rotation has been completed and the resulting chunk
43 * can now safely be read.
45 LTTNG_ROTATION_STATE_COMPLETED
= 2,
47 * The rotation has expired.
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.
53 * Note that this state does not guarantee the the rotation was
54 * completed successfully.
56 LTTNG_ROTATION_STATE_EXPIRED
= 3,
58 * The rotation could not be completed due to an error.
60 LTTNG_ROTATION_STATE_ERROR
= 4,
63 enum lttng_rotation_status
{
64 LTTNG_ROTATION_STATUS_OK
= 0,
65 /* Information not available. */
66 LTTNG_ROTATION_STATUS_UNAVAILABLE
= 1,
68 LTTNG_ROTATION_STATUS_ERROR
= -1,
69 /* Invalid parameters provided. */
70 LTTNG_ROTATION_STATUS_INVALID
= -2,
74 * Input parameter to the lttng_rotate_session command.
76 * An immediate rotation is performed as soon as possible by the tracers.
78 struct lttng_rotation_immediate_attr
;
81 * Input parameter to the lttng_rotate_schedule command.
83 struct lttng_rotation_schedule_attr
;
86 * Handle used to represent a specific rotation.
88 struct lttng_rotation_handle
;
91 * Return a newly allocated session rotation schedule descriptor object or NULL
94 * The rotation schedule may be expressed as a size or as a time period.
96 extern struct lttng_rotation_schedule_attr
*
97 lttng_rotation_schedule_attr_create(void);
100 * Destroy a given scheduled rotate session descriptor object.
102 extern void lttng_rotation_schedule_attr_destroy(
103 struct lttng_rotation_schedule_attr
*attr
);
106 * Set the timer to periodically rotate the session (in µs).
108 extern enum lttng_rotation_status
lttng_rotation_schedule_attr_set_timer_period(
109 struct lttng_rotation_schedule_attr
*attr
, uint64_t timer
);
112 * Set the size to rotate the session (in bytes).
114 void lttng_rotation_schedule_attr_set_size(
115 struct lttng_rotation_schedule_attr
*attr
, uint64_t size
);
118 * lttng rotate session handle functions.
122 * Get the current state of the rotation referenced by the handle.
124 * This will issue a request to the session daemon on every call. Hence,
125 * the result of this call may change over time.
127 extern enum lttng_rotation_status
lttng_rotation_handle_get_state(
128 struct lttng_rotation_handle
*rotation_handle
,
129 enum lttng_rotation_state
*rotation_state
);
132 * Get the location of the rotation's resulting archive.
134 * The rotation must be completed in order for this call to succeed.
135 * The location returned remains owned by the rotation handle.
137 * Note that location will not be set in case of error, or if the session
138 * rotation handle has expired.
140 extern enum lttng_rotation_status
lttng_rotation_handle_get_archive_location(
141 struct lttng_rotation_handle
*rotation_handle
,
142 const struct lttng_trace_archive_location
**location
);
145 * Destroy an lttng_rotate_session handle.
147 extern void lttng_rotation_handle_destroy(
148 struct lttng_rotation_handle
*rotation_handle
);
151 * Rotate the output folder of the session.
153 * On success, handle is allocated and can be used to monitor the progress
154 * of the rotation with lttng_rotation_get_state(). The handle must be freed
155 * by the caller with lttng_rotation_handle_destroy().
157 * Passing NULL as the immediate rotation attribute results in the default
158 * options being used.
160 * Return 0 if the rotate action was successfully launched or a negative
161 * LTTng error code on error.
163 extern int lttng_rotate_session(const char *session_name
,
164 struct lttng_rotation_immediate_attr
*attr
,
165 struct lttng_rotation_handle
**rotation_handle
);
168 * Configure a session to rotate according to a given schedule.
170 extern int lttng_rotation_set_schedule(const char *session_name
,
171 struct lttng_rotation_schedule_attr
*attr
);
174 * Ask the sessiond for the value of the rotate timer (in micro-seconds) of the
177 * On success, return 0 and set the value or rotate_timer, on error return a
180 extern int lttng_rotation_schedule_get_timer_period(const char *session_name
,
181 uint64_t *rotate_timer
);
184 * Ask the sessiond for the value of the rotate size (in micro-seconds) of the
187 * On success, return 0 and set the value or rotate_size, on error return
190 extern int lttng_rotation_schedule_get_size(const char *session_name
,
191 uint64_t *rotate_size
);
197 #endif /* LTTNG_ROTATION_H */