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
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /*
  29  * Return codes for lttng_rotation_handle_get_state()
  30  */
  31 enum lttng_rotation_state {
  32         /*
  33          * Session has not been rotated.
  34          */
  35         LTTNG_ROTATION_STATE_NO_ROTATION = 0,
  36         /*
  37          * Rotation is ongoing, but has not been completed yet.
  38          */
  39         LTTNG_ROTATION_STATE_ONGOING = 1,
  40         /*
  41          * Rotation has been completed and the resulting chunk
  42          * can now safely be read.
  43          */
  44         LTTNG_ROTATION_STATE_COMPLETED = 2,
  45         /*
  46          * The rotation has expired.
  47          *
  48          * The information associated with a given rotation is eventually
  49          * purged by the session daemon. In such a case, the attributes of
  50          * the rotation, such as its path, may no longer be available.
  51          *
  52          * Note that this state does not guarantee the the rotation was
  53          * completed successfully.
  54          */
  55         LTTNG_ROTATION_STATE_EXPIRED = 3,
  56         /*
  57          * The rotation could not be completed due to an error.
  58          */
  59         LTTNG_ROTATION_STATE_ERROR = 4,
  60 };
  61
  62 enum lttng_rotation_status {
  63         LTTNG_ROTATION_STATUS_OK = 0,
  64         /* Information not available. */
  65         LTTNG_ROTATION_STATUS_UNAVAILABLE = 1,
  66         /* Generic error. */
  67         LTTNG_ROTATION_STATUS_ERROR = -1,
  68         /* Invalid parameters provided. */
  69         LTTNG_ROTATION_STATUS_INVALID = -2,
  70 };
  71
  72 /*
  73  * Input parameter to the lttng_rotate_session command.
  74  *
  75  * An immediate rotation is performed as soon as possible by the tracers.
  76  */
  77 struct lttng_rotation_immediate_attr;
  78
  79 /*
  80  * Input parameter to the lttng_rotate_schedule command.
  81  */
  82 struct lttng_rotation_schedule_attr;
  83
  84 /*
  85  * Handle used to represent a specific rotation.
  86  */
  87 struct lttng_rotation_handle;
  88
  89 /*
  90  * Return a newly allocated immediate session rotation descriptor object or NULL
  91  * on error.
  92  */
  93 extern struct lttng_rotation_immediate_attr *
  94 lttng_rotation_immediate_attr_create(void);
  95
  96 /*
  97  * Return a newly allocated scheduled rotate session descriptor object or NULL
  98  * on error.
  99  */
 100 extern struct lttng_rotation_schedule_attr *
 101 lttng_rotation_schedule_attr_create(void);
 102
 103 /*
 104  * Destroy a given immediate session rotation descriptor object.
 105  */
 106 extern void lttng_rotation_immediate_attr_destroy(
 107                 struct lttng_rotation_immediate_attr *attr);
 108
 109 /*
 110  * Destroy a given scheduled rotate session descriptor object.
 111  */
 112 extern void lttng_rotation_schedule_attr_destroy(
 113                 struct lttng_rotation_schedule_attr *attr);
 114
 115 /*
 116  * Set the name of the session to rotate immediately.
 117  *
 118  * The session_name parameter is copied to the immediate session rotation
 119  * attributes.
 120  */
 121 extern enum lttng_rotation_status lttng_rotation_immediate_attr_set_session_name(
 122                 struct lttng_rotation_immediate_attr *attr,
 123                 const char *session_name);
 124
 125 /*
 126  * Set the name of the session to rotate automatically.
 127  *
 128  * The session_name parameter is copied to the immediate session rotation
 129  * attributes.
 130  */
 131 extern enum lttng_rotation_status lttng_rotation_schedule_attr_set_session_name(
 132                 struct lttng_rotation_schedule_attr *attr,
 133                 const char *session_name);
 134
 135 /*
 136  * Set the timer to periodically rotate the session (µs, -1ULL to disable).
 137  */
 138 extern enum lttng_rotation_status lttng_rotation_schedule_attr_set_timer_period(
 139                 struct lttng_rotation_schedule_attr *attr, uint64_t timer);
 140
 141 /*
 142  * Set the size to rotate the session (bytes, -1ULL to disable).
 143  */
 144 void lttng_rotation_schedule_attr_set_size(
 145                 struct lttng_rotation_schedule_attr *attr, uint64_t size);
 146
 147 /*
 148  * lttng rotate session handle functions.
 149  */
 150
 151 /*
 152  * Get the current state of the rotation referenced by the handle.
 153  *
 154  * This will issue a request to the session daemon on every call. Hence,
 155  * the result of this call may change over time.
 156  */
 157 extern enum lttng_rotation_status lttng_rotation_handle_get_state(
 158                 struct lttng_rotation_handle *rotation_handle,
 159                 enum lttng_rotation_state *rotation_state);
 160
 161 /*
 162  * Get the location of the rotation's resulting archive.
 163  *
 164  * The rotation must be completed in order for this call to succeed.
 165  * The path returned is owned by the rotation handle.
 166  *
 167  * Note that path will not be set in case of error, or if the session
 168  * rotation has expired.
 169  *
 170  * FIXME: Return an lttng_location object instead of a path.
 171  */
 172 extern enum lttng_rotation_status lttng_rotation_handle_get_completed_archive_location(
 173                 struct lttng_rotation_handle *rotation_handle,
 174                 const char **path);
 175
 176 /*
 177  * Destroy an lttng_rotate_session handle.
 178  */
 179 extern void lttng_rotation_handle_destroy(
 180                 struct lttng_rotation_handle *rotation_handle);
 181
 182 /*
 183  * Rotate the output folder of the session
 184  *
 185  * On success, handle is allocated and can be used to monitor the progress
 186  * of the rotation with lttng_rotation_get_state(). The handle must be freed
 187  * by the caller with lttng_rotation_handle_destroy().
 188  *
 189  * Return 0 if the rotate action was successfully launched or a negative
 190  * LTTng error code on error.
 191  */
 192 extern int lttng_rotate_session(struct lttng_rotation_immediate_attr *attr,
 193                 struct lttng_rotation_handle **rotation_handle);
 194
 195 /*
 196  * Configure a session to rotate periodically or based on the size written.
 197  */
 198 extern int lttng_rotation_set_schedule(
 199                 struct lttng_rotation_schedule_attr *attr);
 200
 201 /*
 202  * Ask the sessiond for the value of the rotate timer (in micro-seconds) of the
 203  * session.
 204  *
 205  * On success, return 0 and set the value or rotate_timer, on error return a
 206  * negative value.
 207  */
 208 extern int lttng_rotation_schedule_get_timer_period(const char *session_name,
 209                 uint64_t *rotate_timer);
 210
 211 /*
 212  * Ask the sessiond for the value of the rotate size (in micro-seconds) of the
 213  * session.
 214  *
 215  * On success, return 0 and set the value or rotate_size, on error return
 216  * a negative value.
 217  */
 218 extern int lttng_rotation_schedule_get_size(const char *session_name,
 219                 uint64_t *rotate_size);
 220
 221 #ifdef __cplusplus
 222 }
 223 #endif
 224
 225 #endif /* LTTNG_ROTATION_H */