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 */