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