include/lttng/condition/buffer-usage.h

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