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