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/evaluation.h>
12 #include <lttng/condition/condition.h>
14 #include <lttng/domain.h>
15 #include <lttng/lttng-export.h>
22 * Buffer usage conditions allows an action to be taken whenever a channel's
23 * buffer usage crosses a set threshold.
25 * These conditions are periodically evaluated against the current buffer
26 * usage statistics. The period at which these conditions are evaluated is
27 * governed by the channels' monitor timer.
29 * Note that the use of these conditons does not imply any hysteresis-loop
30 * mechanism. For instance, an upper-bound buffer usage condition set to 75%
31 * will fire everytime the buffer usage goes from a value < 75% to a value that
32 * is >= 75%. The evaluation result does not depend on any lower-bound condition
33 * being reached before the condition is evaluated to true again.
35 * Buffer usage conditions have the following properties:
36 * - the exact name of the session in which the channel to be monitored is
38 * - the domain of the channel to be monitored,
39 * - the exact name of the channel to be monitored,
40 * - a usage threshold, expressed either in bytes or as a fraction of total
43 * Wildcards, regular expressions or other globbing mechanisms are not supported
44 * in buffer usage condition properties.
48 * Create a newly allocated lower-bound buffer usage condition.
50 * A lower-bound buffer usage condition evaluates to true whenever
51 * a buffer's usage _crosses_ the bound that is defined as part of the
52 * condition's properties from high to low. In other words, the condition only
53 * evaluates to true when a buffer's usage transitions from a value higher than
54 * the threshold defined in the condition to a value lower than the threshold
55 * defined in the condition.
57 * Returns a new condition on success, NULL on failure. This condition must be
58 * destroyed using lttng_condition_destroy().
60 LTTNG_EXPORT
extern struct lttng_condition
*
61 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
*
77 lttng_condition_buffer_usage_high_create(void);
80 * Get the buffer usage threshold ratio of a buffer usage condition.
82 * The buffer usage condition's threshold must have been defined as a ratio in
83 * order for this call to succeed.
85 * Returns LTTNG_CONDITION_STATUS_OK on success and a ratio contained by the
86 * interval [0.0, 1.0]. LTTNG_CONDITION_STATUS_INVALID is returned if an invalid
87 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a threshold,
88 * expressed as a ratio of total buffer capacity, was not set prior to this
91 LTTNG_EXPORT
extern enum lttng_condition_status
92 lttng_condition_buffer_usage_get_threshold_ratio(
93 const struct lttng_condition
*condition
,
94 double *threshold_ratio
);
97 * Set the buffer usage threshold ratio of a buffer usage condition.
99 * The threshold ratio passed must be contained by the interval [0.0, 1.0] and
100 * represents a ratio of the channel's buffer's capacity. Setting a threshold,
101 * either as a ratio or as an absolute size in bytes will override any
102 * previously set threshold.
104 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
105 * if invalid paramenters are passed.
107 LTTNG_EXPORT
extern enum lttng_condition_status
108 lttng_condition_buffer_usage_set_threshold_ratio(
109 struct lttng_condition
*condition
,
110 double threshold_ratio
);
113 * Get the buffer usage threshold of a buffer usage condition.
115 * The buffer usage condition's threshold must have been defined as an absolute
116 * value expressed in bytes in order for this call to succeed.
118 * Returns LTTNG_CONDITION_STATUS_OK on success and a threshold expressed in
119 * bytes, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed, or
120 * LTTNG_CONDITION_STATUS_UNSET if a threshold, expressed as an absolute size in
121 * bytes, was not set prior to this call.
123 LTTNG_EXPORT
extern enum lttng_condition_status
124 lttng_condition_buffer_usage_get_threshold(
125 const struct lttng_condition
*condition
,
126 uint64_t *threshold_bytes
);
129 * Set the buffer usage threshold in bytes of a buffer usage condition.
131 * Setting a threshold, either as a ratio or as an absolute size in bytes
132 * will override any previously set threshold.
134 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
135 * if invalid paramenters are passed.
137 LTTNG_EXPORT
extern enum lttng_condition_status
138 lttng_condition_buffer_usage_set_threshold(
139 struct lttng_condition
*condition
,
140 uint64_t threshold_bytes
);
143 * Get the session name property of a buffer usage condition.
145 * The caller does not assume the ownership of the returned session name. The
146 * session name shall only only be used for the duration of the condition's
147 * lifetime, or before a different session name is set.
149 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's session
150 * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
151 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a session name
152 * was not set prior to this call.
154 LTTNG_EXPORT
extern enum lttng_condition_status
155 lttng_condition_buffer_usage_get_session_name(
156 const struct lttng_condition
*condition
,
157 const char **session_name
);
160 * Set the session name property of a buffer usage condition.
162 * The passed session name parameter will be copied to the condition.
164 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
165 * if invalid paramenters are passed.
167 LTTNG_EXPORT
extern enum lttng_condition_status
168 lttng_condition_buffer_usage_set_session_name(
169 struct lttng_condition
*condition
,
170 const char *session_name
);
173 * Get the channel name property of a buffer usage condition.
175 * The caller does not assume the ownership of the returned channel name. The
176 * channel name shall only only be used for the duration of the condition's
177 * lifetime, or before a different channel name is set.
179 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's channel
180 * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
181 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a channel name
182 * was not set prior to this call.
184 LTTNG_EXPORT
extern enum lttng_condition_status
185 lttng_condition_buffer_usage_get_channel_name(
186 const struct lttng_condition
*condition
,
187 const char **channel_name
);
190 * Set the channel name property of a buffer usage condition.
192 * The passed channel name parameter will be copied to the condition.
194 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
195 * if invalid paramenters are passed.
197 LTTNG_EXPORT
extern enum lttng_condition_status
198 lttng_condition_buffer_usage_set_channel_name(
199 struct lttng_condition
*condition
,
200 const char *channel_name
);
203 * Get the domain type property of a buffer usage condition.
205 * Returns LTTNG_CONDITION_STATUS_OK and sets the domain type output parameter
206 * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed,
207 * or LTTNG_CONDITION_STATUS_UNSET if a domain type was not set prior to this
210 LTTNG_EXPORT
extern enum lttng_condition_status
211 lttng_condition_buffer_usage_get_domain_type(
212 const struct lttng_condition
*condition
,
213 enum lttng_domain_type
*type
);
216 * Set the domain type property of a buffer usage condition.
218 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
219 * if invalid paramenters are passed.
221 LTTNG_EXPORT
extern enum lttng_condition_status
222 lttng_condition_buffer_usage_set_domain_type(
223 struct lttng_condition
*condition
,
224 enum lttng_domain_type type
);
228 * lttng_evaluation_buffer_usage are specialised lttng_evaluations which
229 * allow users to query a number of properties resulting from the evaluation
230 * of a condition which evaluated to true.
232 * The evaluation of a buffer usage condition yields two different results:
233 * - the usage ratio of the channel buffers at the time of the evaluation,
234 * - the usage, in bytes, of the channel buffers at the time of evaluation.
238 * Get the buffer usage ratio property of a buffer usage evaluation.
240 * Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed as
241 * as a ratio of the buffer's capacity, or LTTNG_EVALUATION_STATUS_INVALID if
242 * an invalid parameter is passed.
244 LTTNG_EXPORT
extern enum lttng_evaluation_status
245 lttng_evaluation_buffer_usage_get_usage_ratio(
246 const struct lttng_evaluation
*evaluation
,
247 double *usage_ratio
);
250 * Get the buffer usage property of a buffer usage evaluation.
252 * Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed in
253 * bytes, or LTTNG_EVALUATION_STATUS_INVALID if an invalid parameter is passed.
255 LTTNG_EXPORT
extern enum lttng_evaluation_status
256 lttng_evaluation_buffer_usage_get_usage(
257 const struct lttng_evaluation
*evaluation
,
258 uint64_t *usage_bytes
);
264 #endif /* LTTNG_CONDITION_BUFFER_USAGE_H */
This page took 0.06913 seconds and 4 git commands to generate.