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