8f1679fc1a14a60552cb656e605425d17e8789cf
[lttng-tools.git] / include / lttng / condition / buffer-usage.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_BUFFER_USAGE_H
19 #define LTTNG_CONDITION_BUFFER_USAGE_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 * Buffer usage conditions allows an action to be taken whenever a channel's
35 * buffer usage crosses a set threshold.
36 *
37 * These conditions are periodically evaluated against the current buffer
38 * usage statistics. The period at which these conditions are evaluated is
39 * governed by the channels' monitor timer.
40 *
41 * Note that the use of these conditons does not imply any hysteresis-loop
42 * mechanism. For instance, an upper-bound buffer usage condition set to 75%
43 * will fire everytime the buffer usage goes from a value < 75% to a value that
44 * is >= 75%. The evaluation result does not depend on any lower-bound condition
45 * being reached before the condition is evaluated to true again.
46 *
47 * Buffer usage conditions have the following properties:
48 * - the exact name of the session in which the channel to be monitored is
49 * defined,
50 * - the domain of the channel to be monitored,
51 * - the exact name of the channel to be monitored,
52 * - a usage threshold, expressed either in bytes or as a fraction of total
53 * buffer capacity.
54 *
55 * Wildcards, regular expressions or other globbing mechanisms are not supported
56 * in buffer usage condition properties.
57 */
58
59 /*
60 * Create a newly allocated lower-bound buffer usage condition.
61 *
62 * A lower-bound buffer usage condition evaluates to true whenever
63 * a buffer's usage _crosses_ the bound that is defined as part of the
64 * condition's properties from high to low. In other words, the condition only
65 * evaluates to true when a buffer's usage transitions from a value higher than
66 * the threshold defined in the condition to a value lower than the threshold
67 * defined in the condition.
68 *
69 * Returns a new condition on success, NULL on failure. This condition must be
70 * destroyed using lttng_condition_destroy().
71 */
72 extern struct lttng_condition *
73 lttng_condition_buffer_usage_low_create(void);
74
75 /*
76 * Create a newly allocated upper-bound buffer usage condition.
77 *
78 * An upper-bound buffer usage condition evaluates to true whenever
79 * a buffer's usage _crosses_ the bound that is defined as part of the
80 * condition's properties from low to high. In other words, the condition only
81 * evaluates to true when a buffer's usage transitions from a value lower than
82 * the threshold defined in the condition to a value higher than the threshold
83 * defined in the condition.
84 *
85 * Returns a new condition on success, NULL on failure. This condition must be
86 * destroyed using lttng_condition_destroy().
87 */
88 extern struct lttng_condition *
89 lttng_condition_buffer_usage_high_create(void);
90
91 /*
92 * Get the buffer usage threshold ratio of a buffer usage condition.
93 *
94 * The buffer usage condition's threshold must have been defined as a ratio in
95 * order for this call to succeed.
96 *
97 * Returns LTTNG_CONDITION_STATUS_OK on success and a ratio contained by the
98 * interval [0.0, 1.0]. LTTNG_CONDITION_STATUS_INVALID is returned if an invalid
99 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a threshold,
100 * expressed as a ratio of total buffer capacity, was not set prior to this
101 * call.
102 */
103 extern enum lttng_condition_status
104 lttng_condition_buffer_usage_get_threshold_ratio(
105 const struct lttng_condition *condition,
106 double *threshold_ratio);
107
108 /*
109 * Set the buffer usage threshold ratio of a buffer usage condition.
110 *
111 * The threshold ratio passed must be contained by the interval [0.0, 1.0] and
112 * represents a ratio of the channel's buffer's capacity. Setting a threshold,
113 * either as a ratio or as an absolute size in bytes will override any
114 * previously set threshold.
115 *
116 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
117 * if invalid paramenters are passed.
118 */
119 extern enum lttng_condition_status
120 lttng_condition_buffer_usage_set_threshold_ratio(
121 struct lttng_condition *condition,
122 double threshold_ratio);
123
124 /*
125 * Get the buffer usage threshold of a buffer usage condition.
126 *
127 * The buffer usage condition's threshold must have been defined as an absolute
128 * value expressed in bytes in order for this call to succeed.
129 *
130 * Returns LTTNG_CONDITION_STATUS_OK on success and a threshold expressed in
131 * bytes, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed, or
132 * LTTNG_CONDITION_STATUS_UNSET if a threshold, expressed as an absolute size in
133 * bytes, was not set prior to this call.
134 */
135 extern enum lttng_condition_status
136 lttng_condition_buffer_usage_get_threshold(
137 const struct lttng_condition *condition,
138 uint64_t *threshold_bytes);
139
140 /*
141 * Set the buffer usage threshold in bytes of a buffer usage condition.
142 *
143 * Setting a threshold, either as a ratio or as an absolute size in bytes
144 * will override any previously set threshold.
145 *
146 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
147 * if invalid paramenters are passed.
148 */
149 extern enum lttng_condition_status
150 lttng_condition_buffer_usage_set_threshold(
151 struct lttng_condition *condition,
152 uint64_t threshold_bytes);
153
154 /*
155 * Get the session name property of a buffer usage condition.
156 *
157 * The caller does not assume the ownership of the returned session name. The
158 * session name shall only only be used for the duration of the condition's
159 * lifetime, or before a different session name is set.
160 *
161 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's session
162 * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
163 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a session name
164 * was not set prior to this call.
165 */
166 extern enum lttng_condition_status
167 lttng_condition_buffer_usage_get_session_name(
168 const struct lttng_condition *condition,
169 const char **session_name);
170
171 /*
172 * Set the session name property of a buffer usage condition.
173 *
174 * The passed session name parameter will be copied to the condition.
175 *
176 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
177 * if invalid paramenters are passed.
178 */
179 extern enum lttng_condition_status
180 lttng_condition_buffer_usage_set_session_name(
181 struct lttng_condition *condition,
182 const char *session_name);
183
184 /*
185 * Get the channel name property of a buffer usage condition.
186 *
187 * The caller does not assume the ownership of the returned channel name. The
188 * channel name shall only only be used for the duration of the condition's
189 * lifetime, or before a different channel name is set.
190 *
191 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's channel
192 * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
193 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a channel name
194 * was not set prior to this call.
195 */
196 extern enum lttng_condition_status
197 lttng_condition_buffer_usage_get_channel_name(
198 const struct lttng_condition *condition,
199 const char **channel_name);
200
201 /*
202 * Set the channel name property of a buffer usage condition.
203 *
204 * The passed channel name parameter will be copied to the condition.
205 *
206 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
207 * if invalid paramenters are passed.
208 */
209 extern enum lttng_condition_status
210 lttng_condition_buffer_usage_set_channel_name(
211 struct lttng_condition *condition,
212 const char *channel_name);
213
214 /*
215 * Get the domain type property of a buffer usage condition.
216 *
217 * Returns LTTNG_CONDITION_STATUS_OK and sets the domain type output parameter
218 * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed,
219 * or LTTNG_CONDITION_STATUS_UNSET if a domain type was not set prior to this
220 * call.
221 */
222 extern enum lttng_condition_status
223 lttng_condition_buffer_usage_get_domain_type(
224 const struct lttng_condition *condition,
225 enum lttng_domain_type *type);
226
227 /*
228 * Set the domain type property of a buffer usage condition.
229 *
230 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
231 * if invalid paramenters are passed.
232 */
233 extern enum lttng_condition_status
234 lttng_condition_buffer_usage_set_domain_type(
235 struct lttng_condition *condition,
236 enum lttng_domain_type type);
237
238
239 /**
240 * lttng_evaluation_buffer_usage are specialised lttng_evaluations which
241 * allow users to query a number of properties resulting from the evaluation
242 * of a condition which evaluated to true.
243 *
244 * The evaluation of a buffer usage condition yields two different results:
245 * - the usage ratio of the channel buffers at the time of the evaluation,
246 * - the usage, in bytes, of the channel buffers at the time of evaluation.
247 */
248
249 /*
250 * Get the buffer usage ratio property of a buffer usage evaluation.
251 *
252 * Returns LTTNG_CONDITION_STATUS_OK on success and a threshold expressed as
253 * as a ratio of the buffer's capacity, or LTTNG_CONDITION_STATUS_INVALID if
254 * an invalid parameter is passed.
255 */
256 extern enum lttng_evaluation_status
257 lttng_evaluation_buffer_usage_get_usage_ratio(
258 const struct lttng_evaluation *evaluation,
259 double *usage_ratio);
260
261 /*
262 * Get the buffer usage property of a buffer usage evaluation.
263 *
264 * Returns LTTNG_CONDITION_STATUS_OK on success and a threshold expressed in
265 * bytes, or LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed.
266 */
267 extern enum lttng_evaluation_status
268 lttng_evaluation_buffer_usage_get_usage(
269 const struct lttng_evaluation *evaluation,
270 uint64_t *usage_bytes);
271
272 #ifdef __cplusplus
273 }
274 #endif
275
276 #endif /* LTTNG_CONDITION_BUFFER_USAGE_H */
This page took 0.052045 seconds and 4 git commands to generate.