include/lttng/condition/buffer-usage.h

   1 /*
   2  * Copyright (C) 2017 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * This library is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU Lesser General Public License, version 2.1 only,
   6  * as published by the Free Software Foundation.
   7  *
   8  * This library is distributed in the hope that it will be useful, but WITHOUT
   9  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
  11  * for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public License
  14  * along with this library; if not, write to the Free Software Foundation,
  15  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  16  */
  17
  18 #ifndef LTTNG_CONDITION_BUFFER_USAGE_H
  19 #define LTTNG_CONDITION_BUFFER_USAGE_H
  20
  21 #include <lttng/condition/evaluation.h>
  22 #include <lttng/condition/condition.h>
  23 #include <stdint.h>
  24 #include <lttng/domain.h>
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /**
  31  * Buffer usage conditions allows an action to be taken whenever a channel's
  32  * buffer usage crosses a set threshold.
  33  *
  34  * These conditions are periodically evaluated against the current buffer
  35  * usage statistics. The period at which these conditions are evaluated is
  36  * governed by the channels' monitor timer.
  37  *
  38  * Note that the use of these conditons does not imply any hysteresis-loop
  39  * mechanism. For instance, an upper-bound buffer usage condition set to 75%
  40  * will fire everytime the buffer usage goes from a value < 75% to a value that
  41  * is >= 75%. The evaluation result does not depend on any lower-bound condition
  42  * being reached before the condition is evaluated to true again.
  43  *
  44  * Buffer usage conditions have the following properties:
  45  *   - the exact name of the session in which the channel to be monitored is
  46  *     defined,
  47  *   - the domain of the channel to be monitored,
  48  *   - the exact name of the channel to be monitored,
  49  *   - a usage threshold, expressed either in bytes or as a fraction of total
  50  *     buffer capacity.
  51  *
  52  * Wildcards, regular expressions or other globbing mechanisms are not supported
  53  * in buffer usage condition properties.
  54  */
  55
  56 /*
  57  * Create a newly allocated lower-bound buffer usage condition.
  58  *
  59  * A lower-bound buffer usage condition evaluates to true whenever
  60  * a buffer's usage _crosses_ the bound that is defined as part of the
  61  * condition's properties from high to low. In other words, the condition only
  62  * evaluates to true when a buffer's usage transitions from a value higher than
  63  * the threshold defined in the condition to a value lower than the threshold
  64  * defined in the condition.
  65  *
  66  * Returns a new condition on success, NULL on failure. This condition must be
  67  * destroyed using lttng_condition_destroy().
  68  */
  69 extern struct lttng_condition *
  70 lttng_condition_buffer_usage_low_create(void);
  71
  72 /*
  73  * Create a newly allocated upper-bound buffer usage condition.
  74  *
  75  * An upper-bound buffer usage condition evaluates to true whenever
  76  * a buffer's usage _crosses_ the bound that is defined as part of the
  77  * condition's properties from low to high. In other words, the condition only
  78  * evaluates to true when a buffer's usage transitions from a value lower than
  79  * the threshold defined in the condition to a value higher than the threshold
  80  * defined in the condition.
  81  *
  82  * Returns a new condition on success, NULL on failure. This condition must be
  83  * destroyed using lttng_condition_destroy().
  84  */
  85 extern struct lttng_condition *
  86 lttng_condition_buffer_usage_high_create(void);
  87
  88 /*
  89  * Get the buffer usage threshold ratio of a buffer usage condition.
  90  *
  91  * The buffer usage condition's threshold must have been defined as a ratio in
  92  * order for this call to succeed.
  93  *
  94  * Returns LTTNG_CONDITION_STATUS_OK on success and a ratio contained by the
  95  * interval [0.0, 1.0]. LTTNG_CONDITION_STATUS_INVALID is returned if an invalid
  96  * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a threshold,
  97  * expressed as a ratio of total buffer capacity, was not set prior to this
  98  * call.
  99  */
 100 extern enum lttng_condition_status
 101 lttng_condition_buffer_usage_get_threshold_ratio(
 102                 const struct lttng_condition *condition,
 103                 double *threshold_ratio);
 104
 105 /*
 106  * Set the buffer usage threshold ratio of a buffer usage condition.
 107  *
 108  * The threshold ratio passed must be contained by the interval [0.0, 1.0] and
 109  * represents a ratio of the channel's buffer's capacity. Setting a threshold,
 110  * either as a ratio or as an absolute size in bytes will override any
 111  * previously set threshold.
 112  *
 113  * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
 114  * if invalid paramenters are passed.
 115  */
 116 extern enum lttng_condition_status
 117 lttng_condition_buffer_usage_set_threshold_ratio(
 118                 struct lttng_condition *condition,
 119                 double threshold_ratio);
 120
 121 /*
 122  * Get the buffer usage threshold of a buffer usage condition.
 123  *
 124  * The buffer usage condition's threshold must have been defined as an absolute
 125  * value expressed in bytes in order for this call to succeed.
 126  *
 127  * Returns LTTNG_CONDITION_STATUS_OK on success and a threshold expressed in
 128  * bytes, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed, or
 129  * LTTNG_CONDITION_STATUS_UNSET if a threshold, expressed as an absolute size in
 130  * bytes, was not set prior to this call.
 131  */
 132 extern enum lttng_condition_status
 133 lttng_condition_buffer_usage_get_threshold(
 134                 const struct lttng_condition *condition,
 135                 uint64_t *threshold_bytes);
 136
 137 /*
 138  * Set the buffer usage threshold in bytes of a buffer usage condition.
 139  *
 140  * Setting a threshold, either as a ratio or as an absolute size in bytes
 141  * will override any previously set threshold.
 142  *
 143  * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
 144  * if invalid paramenters are passed.
 145  */
 146 extern enum lttng_condition_status
 147 lttng_condition_buffer_usage_set_threshold(
 148                 struct lttng_condition *condition,
 149                 uint64_t threshold_bytes);
 150
 151 /*
 152  * Get the session name property of a buffer usage condition.
 153  *
 154  * The caller does not assume the ownership of the returned session name. The
 155  * session name shall only only be used for the duration of the condition's
 156  * lifetime, or before a different session name is set.
 157  *
 158  * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's session
 159  * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
 160  * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a session name
 161  * was not set prior to this call.
 162  */
 163 extern enum lttng_condition_status
 164 lttng_condition_buffer_usage_get_session_name(
 165                 const struct lttng_condition *condition,
 166                 const char **session_name);
 167
 168 /*
 169  * Set the session name property of a buffer usage condition.
 170  *
 171  * The passed session name parameter will be copied to the condition.
 172  *
 173  * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
 174  * if invalid paramenters are passed.
 175  */
 176 extern enum lttng_condition_status
 177 lttng_condition_buffer_usage_set_session_name(
 178                 struct lttng_condition *condition,
 179                 const char *session_name);
 180
 181 /*
 182  * Get the channel name property of a buffer usage condition.
 183  *
 184  * The caller does not assume the ownership of the returned channel name. The
 185  * channel name shall only only be used for the duration of the condition's
 186  * lifetime, or before a different channel name is set.
 187  *
 188  * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's channel
 189  * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
 190  * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a channel name
 191  * was not set prior to this call.
 192  */
 193 extern enum lttng_condition_status
 194 lttng_condition_buffer_usage_get_channel_name(
 195                 const struct lttng_condition *condition,
 196                 const char **channel_name);
 197
 198 /*
 199  * Set the channel name property of a buffer usage condition.
 200  *
 201  * The passed channel name parameter will be copied to the condition.
 202  *
 203  * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
 204  * if invalid paramenters are passed.
 205  */
 206 extern enum lttng_condition_status
 207 lttng_condition_buffer_usage_set_channel_name(
 208                 struct lttng_condition *condition,
 209                 const char *channel_name);
 210
 211 /*
 212  * Get the domain type property of a buffer usage condition.
 213  *
 214  * Returns LTTNG_CONDITION_STATUS_OK and sets the domain type output parameter
 215  * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed,
 216  * or LTTNG_CONDITION_STATUS_UNSET if a domain type was not set prior to this
 217  * call.
 218  */
 219 extern enum lttng_condition_status
 220 lttng_condition_buffer_usage_get_domain_type(
 221                 const struct lttng_condition *condition,
 222                 enum lttng_domain_type *type);
 223
 224 /*
 225  * Set the domain type property of a buffer usage condition.
 226  *
 227  * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
 228  * if invalid paramenters are passed.
 229  */
 230 extern enum lttng_condition_status
 231 lttng_condition_buffer_usage_set_domain_type(
 232                 struct lttng_condition *condition,
 233                 enum lttng_domain_type type);
 234
 235
 236 /**
 237  * lttng_evaluation_buffer_usage are specialised lttng_evaluations which
 238  * allow users to query a number of properties resulting from the evaluation
 239  * of a condition which evaluated to true.
 240  *
 241  * The evaluation of a buffer usage condition yields two different results:
 242  *   - the usage ratio of the channel buffers at the time of the evaluation,
 243  *   - the usage, in bytes, of the channel buffers at the time of evaluation.
 244  */
 245
 246 /*
 247  * Get the buffer usage ratio property of a buffer usage evaluation.
 248  *
 249  * Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed as
 250  * as a ratio of the buffer's capacity, or LTTNG_EVALUATION_STATUS_INVALID if
 251  * an invalid parameter is passed.
 252  */
 253 extern enum lttng_evaluation_status
 254 lttng_evaluation_buffer_usage_get_usage_ratio(
 255                 const struct lttng_evaluation *evaluation,
 256                 double *usage_ratio);
 257
 258 /*
 259  * Get the buffer usage property of a buffer usage evaluation.
 260  *
 261  * Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed in
 262  * bytes, or LTTNG_EVALUATION_STATUS_INVALID if an invalid parameter is passed.
 263  */
 264 extern enum lttng_evaluation_status
 265 lttng_evaluation_buffer_usage_get_usage(
 266                 const struct lttng_evaluation *evaluation,
 267                 uint64_t *usage_bytes);
 268
 269 #ifdef __cplusplus
 270 }
 271 #endif
 272
 273 #endif /* LTTNG_CONDITION_BUFFER_USAGE_H */