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 = 4,
  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 };
  72
  73 /*
  74  * Input parameter to the lttng_rotate_session command.
  75  *
  76  * An immediate rotation is performed as soon as possible by the tracers.
  77  */
  78 struct lttng_rotation_immediate_attr;
  79
  80 /*
  81  * Input parameter to the lttng_rotate_schedule command.
  82  */
  83 struct lttng_rotation_schedule_attr;
  84
  85 /*
  86  * Handle used to represent a specific rotation.
  87  */
  88 struct lttng_rotation_handle;
  89
  90 /*
  91  * Return a newly allocated immediate session rotation descriptor object or NULL
  92  * on error.
  93  */
  94 extern struct lttng_rotation_immediate_attr *
  95 lttng_rotation_immediate_attr_create(void);
  96
  97 /*
  98  * Return a newly allocated scheduled rotate session descriptor object or NULL
  99  * on error.
 100  */
 101 extern struct lttng_rotation_schedule_attr *
 102 lttng_rotation_schedule_attr_create(void);
 103
 104 /*
 105  * Destroy a given immediate session rotation descriptor object.
 106  */
 107 extern void lttng_rotation_immediate_attr_destroy(
 108                 struct lttng_rotation_immediate_attr *attr);
 109
 110 /*
 111  * Destroy a given scheduled rotate session descriptor object.
 112  */
 113 extern void lttng_rotation_schedule_attr_destroy(
 114                 struct lttng_rotation_schedule_attr *attr);
 115
 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  */
 122 extern enum lttng_rotation_status lttng_rotation_immediate_attr_set_session_name(
 123                 struct lttng_rotation_immediate_attr *attr,
 124                 const char *session_name);
 125
 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  */
 132 extern 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  */
 139 extern enum lttng_rotation_status lttng_rotation_schedule_attr_set_timer_period(
 140                 struct lttng_rotation_schedule_attr *attr, uint64_t timer);
 141
 142 /*
 143  * Set the size to rotate the session (bytes, -1ULL to disable).
 144  */
 145 void lttng_rotation_schedule_attr_set_size(
 146                 struct lttng_rotation_schedule_attr *attr, uint64_t size);
 147
 148 /*
 149  * lttng rotate session handle functions.
 150  */
 151
 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  */
 158 extern 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.
 166  * The location returned remains owned by the rotation handle.
 167  *
 168  * Note that location will not be set in case of error, or if the session
 169  * rotation handle has expired.
 170  */
 171 extern enum lttng_rotation_status lttng_rotation_handle_get_archive_location(
 172                 struct lttng_rotation_handle *rotation_handle,
 173                 const struct lttng_trace_archive_location **location);
 174
 175 /*
 176  * Destroy an lttng_rotate_session handle.
 177  */
 178 extern 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  */
 191 extern int lttng_rotate_session(struct lttng_rotation_immediate_attr *attr,
 192                 struct lttng_rotation_handle **rotation_handle);
 193
 194 /*
 195  * Configure a session to rotate periodically or based on the size written.
 196  */
 197 extern int lttng_rotation_set_schedule(
 198                 struct lttng_rotation_schedule_attr *attr);
 199
 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  */
 207 extern 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  */
 217 extern int lttng_rotation_schedule_get_size(const char *session_name,
 218                 uint64_t *rotate_size);
 219
 220 #ifdef __cplusplus
 221 }
 222 #endif
 223
 224 #endif /* LTTNG_ROTATION_H */