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