include/lttng/condition/session-consumed-size.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_SESSION_CONSUMED_SIZE_H
   9 #define LTTNG_CONDITION_SESSION_CONSUMED_SIZE_H
  10
  11 #include <lttng/condition/evaluation.h>
  12 #include <lttng/condition/condition.h>
  13 #include <stdint.h>
  14
  15 #ifdef __cplusplus
  16 extern "C" {
  17 #endif
  18
  19 /**
  20  * Session consumed size conditions allow an action to be taken whenever a
  21  * session's produced data size crosses a set threshold.
  22  *
  23  * These conditions are periodically evaluated against the current session
  24  * statistics. The period at which these conditions are evaluated is
  25  * governed by the channels' monitor timer.
  26  *
  27  * Session consumed size conditions have the following properties:
  28  *   - the exact name of the session to be monitored,
  29  *   - a total consumed size threshold, expressed in bytes.
  30  *
  31  * Wildcards, regular expressions or other globbing mechanisms are not supported
  32  * in session consumed size condition properties.
  33  */
  34
  35 /*
  36  * Create a newly allocated session consumed size condition.
  37  *
  38  * A session consumed size condition evaluates to true whenever the sum of all
  39  * its channels' consumed data size is higher than a set threshold. The
  40  * consumed data sizes are free running counters.
  41  *
  42  * Returns a new condition on success, NULL on failure. This condition must be
  43  * destroyed using lttng_condition_destroy().
  44  */
  45 extern struct lttng_condition *
  46 lttng_condition_session_consumed_size_create(void);
  47
  48 /*
  49  * Get the threshold of a session consumed size condition.
  50  *
  51  * The session consumed size condition's threshold must have been defined as
  52  * an absolute value expressed in bytes in order for this call to succeed.
  53  *
  54  * Returns LTTNG_CONDITION_STATUS_OK on success and a threshold expressed in
  55  * bytes, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed, or
  56  * LTTNG_CONDITION_STATUS_UNSET if a threshold, expressed as an absolute size in
  57  * bytes, was not set prior to this call.
  58  */
  59 extern enum lttng_condition_status
  60 lttng_condition_session_consumed_size_get_threshold(
  61                 const struct lttng_condition *condition,
  62                 uint64_t *consumed_threshold_bytes);
  63
  64 /*
  65  * Set the threshold of a session consumed size usage condition.
  66  *
  67  * Setting a threshold overrides any previously set threshold.
  68  *
  69  * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
  70  * if invalid parameters are passed.
  71  */
  72 extern enum lttng_condition_status
  73 lttng_condition_session_consumed_size_set_threshold(
  74                 struct lttng_condition *condition,
  75                 uint64_t consumed_threshold_bytes);
  76
  77 /*
  78  * Get the session name property of a session consumed size condition.
  79  *
  80  * The caller does not assume the ownership of the returned session name. The
  81  * session name shall only be used for the duration of the condition's
  82  * lifetime, or before a different session name is set.
  83  *
  84  * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's session
  85  * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
  86  * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a session name
  87  * was not set prior to this call.
  88  */
  89 extern enum lttng_condition_status
  90 lttng_condition_session_consumed_size_get_session_name(
  91                 const struct lttng_condition *condition,
  92                 const char **session_name);
  93
  94 /*
  95  * Set the session name property of a session consumed size condition.
  96  *
  97  * The passed session name parameter will be copied to the condition.
  98  *
  99  * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
 100  * if invalid parameters are passed.
 101  */
 102 extern enum lttng_condition_status
 103 lttng_condition_session_consumed_size_set_session_name(
 104                 struct lttng_condition *condition,
 105                 const char *session_name);
 106
 107 /**
 108  * lttng_evaluation_session_consumed_size is specialised lttng_evaluations
 109  * which allow users to query a number of properties resulting from the
 110  * evaluation of a condition which evaluated to true.
 111  */
 112
 113 /*
 114  * Get the session consumed property of a session consumed size evaluation.
 115  *
 116  * Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed in
 117  * bytes, or LTTNG_EVALUATION_STATUS_INVALID if an invalid parameter is passed.
 118  */
 119 extern enum lttng_evaluation_status
 120 lttng_evaluation_session_consumed_size_get_consumed_size(
 121                 const struct lttng_evaluation *evaluation,
 122                 uint64_t *session_consumed);
 123
 124 #ifdef __cplusplus
 125 }
 126 #endif
 127
 128 #endif /* LTTNG_CONDITION_SESSION_CONSUMED_SIZE_H */