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>
21 * Buffer usage conditions allows an action to be taken whenever a channel's
22 * buffer usage crosses a set threshold.
24 * These conditions are periodically evaluated against the current buffer
25 * usage statistics. The period at which these conditions are evaluated is
26 * governed by the channels' monitor timer.
28 * Note that the use of these conditons does not imply any hysteresis-loop
29 * mechanism. For instance, an upper-bound buffer usage condition set to 75%
30 * will fire everytime the buffer usage goes from a value < 75% to a value that
31 * is >= 75%. The evaluation result does not depend on any lower-bound condition
32 * being reached before the condition is evaluated to true again.
34 * Buffer usage conditions have the following properties:
35 * - the exact name of the session in which the channel to be monitored is
37 * - the domain of the channel to be monitored,
38 * - the exact name of the channel to be monitored,
39 * - a usage threshold, expressed either in bytes or as a fraction of total
42 * Wildcards, regular expressions or other globbing mechanisms are not supported
43 * in buffer usage condition properties.
47 * Create a newly allocated lower-bound buffer usage condition.
49 * A lower-bound buffer usage condition evaluates to true whenever
50 * a buffer's usage _crosses_ the bound that is defined as part of the
51 * condition's properties from high to low. In other words, the condition only
52 * evaluates to true when a buffer's usage transitions from a value higher than
53 * the threshold defined in the condition to a value lower than the threshold
54 * defined in the condition.
56 * Returns a new condition on success, NULL on failure. This condition must be
57 * destroyed using lttng_condition_destroy().
59 extern struct lttng_condition
*
60 lttng_condition_buffer_usage_low_create(void);
63 * Create a newly allocated upper-bound buffer usage condition.
65 * An upper-bound buffer usage condition evaluates to true whenever
66 * a buffer's usage _crosses_ the bound that is defined as part of the
67 * condition's properties from low to high. In other words, the condition only
68 * evaluates to true when a buffer's usage transitions from a value lower than
69 * the threshold defined in the condition to a value higher than the threshold
70 * defined in the condition.
72 * Returns a new condition on success, NULL on failure. This condition must be
73 * destroyed using lttng_condition_destroy().
75 extern struct lttng_condition
*
76 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 extern enum lttng_condition_status
91 lttng_condition_buffer_usage_get_threshold_ratio(
92 const struct lttng_condition
*condition
,
93 double *threshold_ratio
);
96 * Set the buffer usage threshold ratio of a buffer usage condition.
98 * The threshold ratio passed must be contained by the interval [0.0, 1.0] and
99 * represents a ratio of the channel's buffer's capacity. Setting a threshold,
100 * either as a ratio or as an absolute size in bytes will override any
101 * previously set threshold.
103 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
104 * if invalid paramenters are passed.
106 extern enum lttng_condition_status
107 lttng_condition_buffer_usage_set_threshold_ratio(
108 struct lttng_condition
*condition
,
109 double threshold_ratio
);
112 * Get the buffer usage threshold of a buffer usage condition.
114 * The buffer usage condition's threshold must have been defined as an absolute
115 * value expressed in bytes in order for this call to succeed.
117 * Returns LTTNG_CONDITION_STATUS_OK on success and a threshold expressed in
118 * bytes, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed, or
119 * LTTNG_CONDITION_STATUS_UNSET if a threshold, expressed as an absolute size in
120 * bytes, was not set prior to this call.
122 extern enum lttng_condition_status
123 lttng_condition_buffer_usage_get_threshold(
124 const struct lttng_condition
*condition
,
125 uint64_t *threshold_bytes
);
128 * Set the buffer usage threshold in bytes of a buffer usage condition.
130 * Setting a threshold, either as a ratio or as an absolute size in bytes
131 * will override any previously set threshold.
133 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
134 * if invalid paramenters are passed.
136 extern enum lttng_condition_status
137 lttng_condition_buffer_usage_set_threshold(
138 struct lttng_condition
*condition
,
139 uint64_t threshold_bytes
);
142 * Get the session name property of a buffer usage condition.
144 * The caller does not assume the ownership of the returned session name. The
145 * session name shall only only be used for the duration of the condition's
146 * lifetime, or before a different session name is set.
148 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's session
149 * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
150 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a session name
151 * was not set prior to this call.
153 extern enum lttng_condition_status
154 lttng_condition_buffer_usage_get_session_name(
155 const struct lttng_condition
*condition
,
156 const char **session_name
);
159 * Set the session name property of a buffer usage condition.
161 * The passed session name parameter will be copied to the condition.
163 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
164 * if invalid paramenters are passed.
166 extern enum lttng_condition_status
167 lttng_condition_buffer_usage_set_session_name(
168 struct lttng_condition
*condition
,
169 const char *session_name
);
172 * Get the channel name property of a buffer usage condition.
174 * The caller does not assume the ownership of the returned channel name. The
175 * channel name shall only only be used for the duration of the condition's
176 * lifetime, or before a different channel name is set.
178 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's channel
179 * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
180 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a channel name
181 * was not set prior to this call.
183 extern enum lttng_condition_status
184 lttng_condition_buffer_usage_get_channel_name(
185 const struct lttng_condition
*condition
,
186 const char **channel_name
);
189 * Set the channel name property of a buffer usage condition.
191 * The passed channel name parameter will be copied to the condition.
193 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
194 * if invalid paramenters are passed.
196 extern enum lttng_condition_status
197 lttng_condition_buffer_usage_set_channel_name(
198 struct lttng_condition
*condition
,
199 const char *channel_name
);
202 * Get the domain type property of a buffer usage condition.
204 * Returns LTTNG_CONDITION_STATUS_OK and sets the domain type output parameter
205 * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed,
206 * or LTTNG_CONDITION_STATUS_UNSET if a domain type was not set prior to this
209 extern enum lttng_condition_status
210 lttng_condition_buffer_usage_get_domain_type(
211 const struct lttng_condition
*condition
,
212 enum lttng_domain_type
*type
);
215 * Set the domain type property of a buffer usage condition.
217 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
218 * if invalid paramenters are passed.
220 extern enum lttng_condition_status
221 lttng_condition_buffer_usage_set_domain_type(
222 struct lttng_condition
*condition
,
223 enum lttng_domain_type type
);
227 * lttng_evaluation_buffer_usage are specialised lttng_evaluations which
228 * allow users to query a number of properties resulting from the evaluation
229 * of a condition which evaluated to true.
231 * The evaluation of a buffer usage condition yields two different results:
232 * - the usage ratio of the channel buffers at the time of the evaluation,
233 * - the usage, in bytes, of the channel buffers at the time of evaluation.
237 * Get the buffer usage ratio property of a buffer usage evaluation.
239 * Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed as
240 * as a ratio of the buffer's capacity, or LTTNG_EVALUATION_STATUS_INVALID if
241 * an invalid parameter is passed.
243 extern enum lttng_evaluation_status
244 lttng_evaluation_buffer_usage_get_usage_ratio(
245 const struct lttng_evaluation
*evaluation
,
246 double *usage_ratio
);
249 * Get the buffer usage property of a buffer usage evaluation.
251 * Returns LTTNG_EVALUATION_STATUS_OK on success and a threshold expressed in
252 * bytes, or LTTNG_EVALUATION_STATUS_INVALID if an invalid parameter is passed.
254 extern enum lttng_evaluation_status
255 lttng_evaluation_buffer_usage_get_usage(
256 const struct lttng_evaluation
*evaluation
,
257 uint64_t *usage_bytes
);
263 #endif /* LTTNG_CONDITION_BUFFER_USAGE_H */
This page took 0.034667 seconds and 4 git commands to generate.