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