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