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