Commit | Line | Data |
---|---|---|
a58c490f | 1 | /* |
ab5be9fa | 2 | * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com> |
a58c490f | 3 | * |
ab5be9fa | 4 | * SPDX-License-Identifier: LGPL-2.1-only |
a58c490f | 5 | * |
a58c490f JG |
6 | */ |
7 | ||
8 | #ifndef LTTNG_CONDITION_BUFFER_USAGE_H | |
9 | #define LTTNG_CONDITION_BUFFER_USAGE_H | |
10 | ||
9d744342 JG |
11 | #include <lttng/condition/evaluation.h> |
12 | #include <lttng/condition/condition.h> | |
b3a57d53 JG |
13 | #include <stdint.h> |
14 | #include <lttng/domain.h> | |
4bd69c5f | 15 | #include <lttng/lttng-export.h> |
9d744342 | 16 | |
a58c490f JG |
17 | #ifdef __cplusplus |
18 | extern "C" { | |
19 | #endif | |
20 | ||
888d24c6 JG |
21 | /** |
22 | * Buffer usage conditions allows an action to be taken whenever a channel's | |
23 | * buffer usage crosses a set threshold. | |
24 | * | |
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. | |
28 | * | |
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. | |
34 | * | |
35 | * Buffer usage conditions have the following properties: | |
36 | * - the exact name of the session in which the channel to be monitored is | |
37 | * defined, | |
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 | |
41 | * buffer capacity. | |
42 | * | |
43 | * Wildcards, regular expressions or other globbing mechanisms are not supported | |
44 | * in buffer usage condition properties. | |
45 | */ | |
46 | ||
47 | /* | |
48 | * Create a newly allocated lower-bound buffer usage condition. | |
49 | * | |
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. | |
56 | * | |
57 | * Returns a new condition on success, NULL on failure. This condition must be | |
58 | * destroyed using lttng_condition_destroy(). | |
59 | */ | |
4bd69c5f | 60 | LTTNG_EXPORT extern struct lttng_condition * |
a58c490f JG |
61 | lttng_condition_buffer_usage_low_create(void); |
62 | ||
888d24c6 JG |
63 | /* |
64 | * Create a newly allocated upper-bound buffer usage condition. | |
65 | * | |
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. | |
72 | * | |
73 | * Returns a new condition on success, NULL on failure. This condition must be | |
74 | * destroyed using lttng_condition_destroy(). | |
75 | */ | |
4bd69c5f | 76 | LTTNG_EXPORT extern struct lttng_condition * |
a58c490f JG |
77 | lttng_condition_buffer_usage_high_create(void); |
78 | ||
888d24c6 JG |
79 | /* |
80 | * Get the buffer usage threshold ratio of a buffer usage condition. | |
81 | * | |
82 | * The buffer usage condition's threshold must have been defined as a ratio in | |
83 | * order for this call to succeed. | |
84 | * | |
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 | |
89 | * call. | |
90 | */ | |
4bd69c5f | 91 | LTTNG_EXPORT extern enum lttng_condition_status |
a58c490f JG |
92 | lttng_condition_buffer_usage_get_threshold_ratio( |
93 | const struct lttng_condition *condition, | |
94 | double *threshold_ratio); | |
95 | ||
888d24c6 JG |
96 | /* |
97 | * Set the buffer usage threshold ratio of a buffer usage condition. | |
98 | * | |
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. | |
103 | * | |
104 | * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID | |
105 | * if invalid paramenters are passed. | |
106 | */ | |
4bd69c5f | 107 | LTTNG_EXPORT extern enum lttng_condition_status |
a58c490f JG |
108 | lttng_condition_buffer_usage_set_threshold_ratio( |
109 | struct lttng_condition *condition, | |
110 | double threshold_ratio); | |
111 | ||
888d24c6 JG |
112 | /* |
113 | * Get the buffer usage threshold of a buffer usage condition. | |
114 | * | |
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. | |
117 | * | |
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. | |
122 | */ | |
4bd69c5f | 123 | LTTNG_EXPORT extern enum lttng_condition_status |
a58c490f JG |
124 | lttng_condition_buffer_usage_get_threshold( |
125 | const struct lttng_condition *condition, | |
126 | uint64_t *threshold_bytes); | |
127 | ||
888d24c6 JG |
128 | /* |
129 | * Set the buffer usage threshold in bytes of a buffer usage condition. | |
130 | * | |
131 | * Setting a threshold, either as a ratio or as an absolute size in bytes | |
132 | * will override any previously set threshold. | |
133 | * | |
134 | * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID | |
135 | * if invalid paramenters are passed. | |
136 | */ | |
4bd69c5f | 137 | LTTNG_EXPORT extern enum lttng_condition_status |
a58c490f JG |
138 | lttng_condition_buffer_usage_set_threshold( |
139 | struct lttng_condition *condition, | |
140 | uint64_t threshold_bytes); | |
141 | ||
888d24c6 JG |
142 | /* |
143 | * Get the session name property of a buffer usage condition. | |
144 | * | |
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. | |
148 | * | |
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. | |
153 | */ | |
4bd69c5f | 154 | LTTNG_EXPORT extern enum lttng_condition_status |
a58c490f JG |
155 | lttng_condition_buffer_usage_get_session_name( |
156 | const struct lttng_condition *condition, | |
157 | const char **session_name); | |
158 | ||
888d24c6 JG |
159 | /* |
160 | * Set the session name property of a buffer usage condition. | |
161 | * | |
162 | * The passed session name parameter will be copied to the condition. | |
163 | * | |
164 | * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID | |
165 | * if invalid paramenters are passed. | |
166 | */ | |
4bd69c5f | 167 | LTTNG_EXPORT extern enum lttng_condition_status |
a58c490f JG |
168 | lttng_condition_buffer_usage_set_session_name( |
169 | struct lttng_condition *condition, | |
170 | const char *session_name); | |
171 | ||
888d24c6 JG |
172 | /* |
173 | * Get the channel name property of a buffer usage condition. | |
174 | * | |
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. | |
178 | * | |
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. | |
183 | */ | |
4bd69c5f | 184 | LTTNG_EXPORT extern enum lttng_condition_status |
a58c490f JG |
185 | lttng_condition_buffer_usage_get_channel_name( |
186 | const struct lttng_condition *condition, | |
187 | const char **channel_name); | |
188 | ||
888d24c6 JG |
189 | /* |
190 | * Set the channel name property of a buffer usage condition. | |
191 | * | |
192 | * The passed channel name parameter will be copied to the condition. | |
193 | * | |
194 | * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID | |
195 | * if invalid paramenters are passed. | |
196 | */ | |
4bd69c5f | 197 | LTTNG_EXPORT extern enum lttng_condition_status |
a58c490f JG |
198 | lttng_condition_buffer_usage_set_channel_name( |
199 | struct lttng_condition *condition, | |
200 | const char *channel_name); | |
201 | ||
888d24c6 JG |
202 | /* |
203 | * Get the domain type property of a buffer usage condition. | |
204 | * | |
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 | |
208 | * call. | |
209 | */ | |
4bd69c5f | 210 | LTTNG_EXPORT extern enum lttng_condition_status |
a58c490f JG |
211 | lttng_condition_buffer_usage_get_domain_type( |
212 | const struct lttng_condition *condition, | |
213 | enum lttng_domain_type *type); | |
214 | ||
888d24c6 JG |
215 | /* |
216 | * Set the domain type property of a buffer usage condition. | |
217 | * | |
218 | * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID | |
219 | * if invalid paramenters are passed. | |
220 | */ | |
4bd69c5f | 221 | LTTNG_EXPORT extern enum lttng_condition_status |
a58c490f JG |
222 | lttng_condition_buffer_usage_set_domain_type( |
223 | struct lttng_condition *condition, | |
224 | enum lttng_domain_type type); | |
225 | ||
226 | ||
888d24c6 JG |
227 | /** |
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. | |
231 | * | |
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. | |
235 | */ | |
236 | ||
237 | /* | |
238 | * Get the buffer usage ratio property of a buffer usage evaluation. | |
239 | * | |
cc02b9d4 JG |
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 | |
888d24c6 JG |
242 | * an invalid parameter is passed. |
243 | */ | |
4bd69c5f | 244 | LTTNG_EXPORT extern enum lttng_evaluation_status |
a58c490f JG |
245 | lttng_evaluation_buffer_usage_get_usage_ratio( |
246 | const struct lttng_evaluation *evaluation, | |
247 | double *usage_ratio); | |
248 | ||
888d24c6 JG |
249 | /* |
250 | * Get the buffer usage property of a buffer usage evaluation. | |
251 | * | |
cc02b9d4 JG |
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. | |
888d24c6 | 254 | */ |
4bd69c5f | 255 | LTTNG_EXPORT extern enum lttng_evaluation_status |
a58c490f JG |
256 | lttng_evaluation_buffer_usage_get_usage( |
257 | const struct lttng_evaluation *evaluation, | |
258 | uint64_t *usage_bytes); | |
259 | ||
260 | #ifdef __cplusplus | |
261 | } | |
262 | #endif | |
263 | ||
264 | #endif /* LTTNG_CONDITION_BUFFER_USAGE_H */ |