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