2 * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
4 * SPDX-License-Identifier: LGPL-2.1-only
8 #ifndef LTTNG_CONDITION_BUFFER_USAGE_H
9 #define LTTNG_CONDITION_BUFFER_USAGE_H
11 #include <lttng/condition/condition.h>
12 #include <lttng/condition/evaluation.h>
13 #include <lttng/domain.h>
14 #include <lttng/lttng-export.h>
23 * Buffer usage conditions allows an action to be taken whenever a channel's
24 * buffer usage crosses a set threshold.
26 * These conditions are periodically evaluated against the current buffer
27 * usage statistics. The period at which these conditions are evaluated is
28 * governed by the channels' monitor timer.
30 * Note that the use of these conditons does not imply any hysteresis-loop
31 * mechanism. For instance, an upper-bound buffer usage condition set to 75%
32 * will fire everytime the buffer usage goes from a value < 75% to a value that
33 * is >= 75%. The evaluation result does not depend on any lower-bound condition
34 * being reached before the condition is evaluated to true again.
36 * Buffer usage conditions have the following properties:
37 * - the exact name of the session in which the channel to be monitored is
39 * - the domain of the channel to be monitored,
40 * - the exact name of the channel to be monitored,
41 * - a usage threshold, expressed either in bytes or as a fraction of total
44 * Wildcards, regular expressions or other globbing mechanisms are not supported
45 * in buffer usage condition properties.
49 * Create a newly allocated lower-bound buffer usage condition.
51 * A lower-bound buffer usage condition evaluates to true whenever
52 * a buffer's usage _crosses_ the bound that is defined as part of the
53 * condition's properties from high to low. In other words, the condition only
54 * evaluates to true when a buffer's usage transitions from a value higher than
55 * the threshold defined in the condition to a value lower than the threshold
56 * defined in the condition.
58 * Returns a new condition on success, NULL on failure. This condition must be
59 * destroyed using lttng_condition_destroy().
61 LTTNG_EXPORT
extern struct lttng_condition
*lttng_condition_buffer_usage_low_create(void);
64 * Create a newly allocated upper-bound buffer usage condition.
66 * An upper-bound buffer usage condition evaluates to true whenever
67 * a buffer's usage _crosses_ the bound that is defined as part of the
68 * condition's properties from low to high. In other words, the condition only
69 * evaluates to true when a buffer's usage transitions from a value lower than
70 * the threshold defined in the condition to a value higher than the threshold
71 * defined in the condition.
73 * Returns a new condition on success, NULL on failure. This condition must be
74 * destroyed using lttng_condition_destroy().
76 LTTNG_EXPORT
extern struct lttng_condition
*lttng_condition_buffer_usage_high_create(void);
79 * Get the buffer usage threshold ratio of a buffer usage condition.
81 * The buffer usage condition's threshold must have been defined as a ratio in
82 * order for this call to succeed.
84 * Returns LTTNG_CONDITION_STATUS_OK on success and a ratio contained by the
85 * interval [0.0, 1.0]. LTTNG_CONDITION_STATUS_INVALID is returned if an invalid
86 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a threshold,
87 * expressed as a ratio of total buffer capacity, was not set prior to this
90 LTTNG_EXPORT
extern enum lttng_condition_status
91 lttng_condition_buffer_usage_get_threshold_ratio(const struct lttng_condition
*condition
,
92 double *threshold_ratio
);
95 * Set the buffer usage threshold ratio of a buffer usage condition.
97 * The threshold ratio passed must be contained by the interval [0.0, 1.0] and
98 * represents a ratio of the channel's buffer's capacity. Setting a threshold,
99 * either as a ratio or as an absolute size in bytes will override any
100 * previously set threshold.
102 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
103 * if invalid paramenters are passed.
105 LTTNG_EXPORT
extern enum lttng_condition_status
106 lttng_condition_buffer_usage_set_threshold_ratio(struct lttng_condition
*condition
,
107 double threshold_ratio
);
110 * Get the buffer usage threshold of a buffer usage condition.
112 * The buffer usage condition's threshold must have been defined as an absolute
113 * value expressed in bytes in order for this call to succeed.
115 * Returns LTTNG_CONDITION_STATUS_OK on success and a threshold expressed in
116 * bytes, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed, or
117 * LTTNG_CONDITION_STATUS_UNSET if a threshold, expressed as an absolute size in
118 * bytes, was not set prior to this call.
120 LTTNG_EXPORT
extern enum lttng_condition_status
121 lttng_condition_buffer_usage_get_threshold(const struct lttng_condition
*condition
,
122 uint64_t *threshold_bytes
);
125 * Set the buffer usage threshold in bytes of a buffer usage condition.
127 * Setting a threshold, either as a ratio or as an absolute size in bytes
128 * will override any previously set threshold.
130 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
131 * if invalid paramenters are passed.
133 LTTNG_EXPORT
extern enum lttng_condition_status
134 lttng_condition_buffer_usage_set_threshold(struct lttng_condition
*condition
,
135 uint64_t threshold_bytes
);
138 * Get the session name property of a buffer usage condition.
140 * The caller does not assume the ownership of the returned session name. The
141 * session name shall only only be used for the duration of the condition's
142 * lifetime, or before a different session name is set.
144 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's session
145 * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
146 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a session name
147 * was not set prior to this call.
149 LTTNG_EXPORT
extern enum lttng_condition_status
150 lttng_condition_buffer_usage_get_session_name(const struct lttng_condition
*condition
,
151 const char **session_name
);
154 * Set the session name property of a buffer usage condition.
156 * The passed session name parameter will be copied to the condition.
158 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
159 * if invalid paramenters are passed.
161 LTTNG_EXPORT
extern enum lttng_condition_status
162 lttng_condition_buffer_usage_set_session_name(struct lttng_condition
*condition
,
163 const char *session_name
);
166 * Get the channel name property of a buffer usage condition.
168 * The caller does not assume the ownership of the returned channel name. The
169 * channel name shall only only be used for the duration of the condition's
170 * lifetime, or before a different channel name is set.
172 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's channel
173 * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
174 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a channel name
175 * was not set prior to this call.
177 LTTNG_EXPORT
extern enum lttng_condition_status
178 lttng_condition_buffer_usage_get_channel_name(const struct lttng_condition
*condition
,
179 const char **channel_name
);
182 * Set the channel name property of a buffer usage condition.
184 * The passed channel name parameter will be copied to the condition.
186 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
187 * if invalid paramenters are passed.
189 LTTNG_EXPORT
extern enum lttng_condition_status
190 lttng_condition_buffer_usage_set_channel_name(struct lttng_condition
*condition
,
191 const char *channel_name
);
194 * Get the domain type property of a buffer usage condition.
196 * Returns LTTNG_CONDITION_STATUS_OK and sets the domain type output parameter
197 * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed,
198 * or LTTNG_CONDITION_STATUS_UNSET if a domain type was not set prior to this
201 LTTNG_EXPORT
extern enum lttng_condition_status
202 lttng_condition_buffer_usage_get_domain_type(const struct lttng_condition
*condition
,
203 enum lttng_domain_type
*type
);
206 * Set the domain type property of a buffer usage condition.
208 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
209 * if invalid paramenters are passed.
211 LTTNG_EXPORT
extern enum lttng_condition_status
212 lttng_condition_buffer_usage_set_domain_type(struct lttng_condition
*condition
,
213 enum lttng_domain_type type
);
216 * lttng_evaluation_buffer_usage are specialised lttng_evaluations which
217 * allow users to query a number of properties resulting from the evaluation
218 * of a condition which evaluated to true.
220 * The evaluation of a buffer usage condition yields two different results:
221 * - the usage ratio of the channel buffers at the time of the evaluation,
222 * - the usage, in bytes, of the channel buffers at the time of evaluation.
226 * Get the buffer usage ratio property of a buffer usage evaluation.
228 * Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed as
229 * as a ratio of the buffer's capacity, or LTTNG_EVALUATION_STATUS_INVALID if
230 * an invalid parameter is passed.
232 LTTNG_EXPORT
extern enum lttng_evaluation_status
233 lttng_evaluation_buffer_usage_get_usage_ratio(const struct lttng_evaluation
*evaluation
,
234 double *usage_ratio
);
237 * Get the buffer usage property of a buffer usage evaluation.
239 * Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed in
240 * bytes, or LTTNG_EVALUATION_STATUS_INVALID if an invalid parameter is passed.
242 LTTNG_EXPORT
extern enum lttng_evaluation_status
243 lttng_evaluation_buffer_usage_get_usage(const struct lttng_evaluation
*evaluation
,
244 uint64_t *usage_bytes
);
250 #endif /* LTTNG_CONDITION_BUFFER_USAGE_H */
This page took 0.034114 seconds and 4 git commands to generate.