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  * SPDX-License-Identifier: LGPL-2.1-only
   6  *
   7  */
   8
   9 #ifndef LTTNG_ROTATION_H
  10 #define LTTNG_ROTATION_H
  11
  12 #include <stdint.h>
  13 #include <lttng/location.h>
  14
  15 #ifdef __cplusplus
  16 extern "C" {
  17 #endif
  18
  19 /*
  20  * Return codes for lttng_rotation_handle_get_state()
  21  */
  22 enum lttng_rotation_state {
  23         /*
  24          * Session has not been rotated.
  25          */
  26         LTTNG_ROTATION_STATE_NO_ROTATION = 0,
  27         /*
  28          * Rotation is ongoing, but has not been completed yet.
  29          */
  30         LTTNG_ROTATION_STATE_ONGOING = 1,
  31         /*
  32          * Rotation has been completed and the resulting chunk
  33          * can now safely be read.
  34          */
  35         LTTNG_ROTATION_STATE_COMPLETED = 2,
  36         /*
  37          * The rotation has expired.
  38          *
  39          * The information associated with a given rotation is eventually
  40          * purged by the session daemon. In such a case, the attributes of
  41          * the rotation, such as its path, may no longer be available.
  42          *
  43          * Note that this state does not guarantee the the rotation was
  44          * completed successfully.
  45          */
  46         LTTNG_ROTATION_STATE_EXPIRED = 3,
  47         /*
  48          * The rotation could not be completed due to an error.
  49          */
  50         LTTNG_ROTATION_STATE_ERROR = -1,
  51 };
  52
  53 enum lttng_rotation_status {
  54         LTTNG_ROTATION_STATUS_OK = 0,
  55         /* Information not available. */
  56         LTTNG_ROTATION_STATUS_UNAVAILABLE = 1,
  57         /* Generic error. */
  58         LTTNG_ROTATION_STATUS_ERROR = -1,
  59         /* Invalid parameters provided. */
  60         LTTNG_ROTATION_STATUS_INVALID = -2,
  61         /* A schedule of this type is already set. */
  62         LTTNG_ROTATION_STATUS_SCHEDULE_ALREADY_SET = -3,
  63         /* No such rotation schedule set. */
  64         LTTNG_ROTATION_STATUS_SCHEDULE_NOT_SET = -3,
  65 };
  66
  67 enum lttng_rotation_schedule_type {
  68         LTTNG_ROTATION_SCHEDULE_TYPE_UNKNOWN = -1,
  69         LTTNG_ROTATION_SCHEDULE_TYPE_SIZE_THRESHOLD = 0,
  70         LTTNG_ROTATION_SCHEDULE_TYPE_PERIODIC = 1,
  71 };
  72
  73 /*
  74  * Descriptor of an immediate session rotation to be performed as soon as
  75  * possible by the tracers.
  76  */
  77 struct lttng_rotation_immediate_descriptor;
  78
  79 /*
  80  * Session rotation schedule to add to a session.
  81  */
  82 struct lttng_rotation_schedule;
  83
  84 /*
  85  * A set of lttng_rotation_schedule objects.
  86  */
  87 struct lttng_rotation_schedules;
  88
  89 /*
  90  * Handle used to represent a specific rotation.
  91  */
  92 struct lttng_rotation_handle;
  93
  94 /*
  95  * lttng rotate session handle functions.
  96  */
  97
  98 /*
  99  * Get the current state of the rotation referenced by the handle.
 100  *
 101  * This will issue a request to the session daemon on every call. Hence,
 102  * the result of this call may change over time.
 103  */
 104 extern enum lttng_rotation_status lttng_rotation_handle_get_state(
 105                 struct lttng_rotation_handle *rotation_handle,
 106                 enum lttng_rotation_state *rotation_state);
 107
 108 /*
 109  * Get the location of the rotation's resulting archive.
 110  *
 111  * The rotation must be completed in order for this call to succeed.
 112  * The location returned remains owned by the rotation handle.
 113  *
 114  * Note that location will not be set in case of error, or if the session
 115  * rotation handle has expired.
 116  */
 117 extern enum lttng_rotation_status lttng_rotation_handle_get_archive_location(
 118                 struct lttng_rotation_handle *rotation_handle,
 119                 const struct lttng_trace_archive_location **location);
 120
 121 /*
 122  * Destroy an lttng_rotate_session handle.
 123  */
 124 extern void lttng_rotation_handle_destroy(
 125                 struct lttng_rotation_handle *rotation_handle);
 126
 127 /*
 128  * Rotate the output folder of the session.
 129  *
 130  * On success, handle is allocated and can be used to monitor the progress
 131  * of the rotation with lttng_rotation_get_state(). The handle must be freed
 132  * by the caller with lttng_rotation_handle_destroy().
 133  *
 134  * Passing NULL as the immediate rotation descriptor results in the default
 135  * options being used.
 136  *
 137  * Return 0 if the rotate action was successfully launched or a negative
 138  * LTTng error code on error.
 139  */
 140 extern int lttng_rotate_session(const char *session_name,
 141                 struct lttng_rotation_immediate_descriptor *descriptor,
 142                 struct lttng_rotation_handle **rotation_handle);
 143
 144 /*
 145  * Get the type of a rotation schedule object.
 146  */
 147 extern enum lttng_rotation_schedule_type lttng_rotation_schedule_get_type(
 148                 const struct lttng_rotation_schedule *schedule);
 149
 150 /*
 151  * Return a newly allocated size-based session rotation schedule or NULL on
 152  * error.
 153  */
 154 extern struct lttng_rotation_schedule *
 155 lttng_rotation_schedule_size_threshold_create(void);
 156
 157 /*
 158  * Get a session rotation schedule's size threshold.
 159  *
 160  * Returns LTTNG_ROTATION_STATUS_OK on success.
 161  * LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset.
 162  */
 163 extern enum lttng_rotation_status
 164 lttng_rotation_schedule_size_threshold_get_threshold(
 165                 const struct lttng_rotation_schedule *schedule,
 166                 uint64_t *size_threshold_bytes);
 167
 168 /*
 169  * Set a session rotation schedule's size threshold.
 170  */
 171 extern enum lttng_rotation_status
 172 lttng_rotation_schedule_size_threshold_set_threshold(
 173                 struct lttng_rotation_schedule *schedule,
 174                 uint64_t size_threshold_bytes);
 175
 176 /*
 177  * Return a newly allocated periodic session rotation schedule or NULL on
 178  * error.
 179  */
 180 extern struct lttng_rotation_schedule *
 181 lttng_rotation_schedule_periodic_create(void);
 182
 183 /*
 184  * Get a time-based session rotation schedule's period.
 185  *
 186  * Returns LTTNG_ROTATION_STATUS_OK on success.
 187  * LTTNG_ROTATION_STATUS_UNAVAILABLE is returned if the value is unset.
 188  */
 189 extern enum lttng_rotation_status lttng_rotation_schedule_periodic_get_period(
 190                 const struct lttng_rotation_schedule *schedule,
 191                 uint64_t *period_us);
 192
 193 /*
 194  * Set a time-based session rotation schedule's period.
 195  */
 196 extern enum lttng_rotation_status lttng_rotation_schedule_periodic_set_period(
 197                 struct lttng_rotation_schedule *schedule,
 198                 uint64_t period_us);
 199
 200 /*
 201  * Destroy a rotation schedule.
 202  */
 203 extern void lttng_rotation_schedule_destroy(
 204                 struct lttng_rotation_schedule *schedule);
 205
 206 /*
 207  * Destroy a set of rotation schedules. Pointers to any schedule contained
 208  * in this set become invalid after this call.
 209  */
 210 extern void lttng_rotation_schedules_destroy(
 211                 struct lttng_rotation_schedules *schedules);
 212
 213 /*
 214  * Get the number of schedules in a schedule set.
 215  */
 216 extern enum lttng_rotation_status lttng_rotation_schedules_get_count(
 217                 const struct lttng_rotation_schedules *schedules,
 218                 unsigned int *count);
 219
 220 /*
 221  * Get a schedule from the set at a given index.
 222  *
 223  * Note that the set maintains the ownership of the returned schedule.
 224  * It must not be destroyed by the user, nor should it be held beyond
 225  * the lifetime of the schedules set.
 226  *
 227  * Returns a rotation schedule, or NULL on error.
 228  */
 229 extern const struct lttng_rotation_schedule *
 230 lttng_rotation_schedules_get_at_index(
 231                 const struct lttng_rotation_schedules *schedules,
 232                 unsigned int index);
 233
 234 /*
 235  * Add a session rotation schedule to a session.
 236  *
 237  * Note that the current implementation currently limits the rotation schedules
 238  * associated to a given session to one per type.
 239  *
 240  * Returns LTTNG_ROTATION_STATUS_OK on success,
 241  * LTTNG_ROTATION_STATUS_SCHEDULE_ALREADY_SET if a rotation of the same type
 242  * is already set.
 243  */
 244 extern enum lttng_rotation_status lttng_session_add_rotation_schedule(
 245                 const char *session_name,
 246                 const struct lttng_rotation_schedule *schedule);
 247
 248 /*
 249  * Remove a session rotation schedule from a session.
 250  *
 251  * Returns LTTNG_ROTATION_STATUS_OK on success,
 252  * LTTNG_ROTATION_STATUS_SCHEDULE_INVALID if the provided schedule is
 253  * not set.
 254  */
 255 extern enum lttng_rotation_status lttng_session_remove_rotation_schedule(
 256                 const char *session_name,
 257                 const struct lttng_rotation_schedule *schedule);
 258
 259 /*
 260  * Get the rotation schedules associated with a given session.
 261  *
 262  * Returns LTTNG_OK on success, or a negative lttng error code on error.
 263  */
 264 extern int lttng_session_list_rotation_schedules(
 265                 const char *session_name,
 266                 struct lttng_rotation_schedules **schedules);
 267
 268 #ifdef __cplusplus
 269 }
 270 #endif
 271
 272 #endif /* LTTNG_ROTATION_H */