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