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