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