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