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