Docs: document the lttng_buffer_usage condition API
[lttng-tools.git] / include / lttng / condition / buffer-usage.h
CommitLineData
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
27extern "C" {
28#endif
29
30struct lttng_condition;
31struct lttng_evaluation;
32
888d24c6
JG
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 */
a58c490f
JG
72extern struct lttng_condition *
73lttng_condition_buffer_usage_low_create(void);
74
888d24c6
JG
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 */
a58c490f
JG
88extern struct lttng_condition *
89lttng_condition_buffer_usage_high_create(void);
90
888d24c6
JG
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 */
a58c490f
JG
103extern enum lttng_condition_status
104lttng_condition_buffer_usage_get_threshold_ratio(
105 const struct lttng_condition *condition,
106 double *threshold_ratio);
107
888d24c6
JG
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 */
a58c490f
JG
119extern enum lttng_condition_status
120lttng_condition_buffer_usage_set_threshold_ratio(
121 struct lttng_condition *condition,
122 double threshold_ratio);
123
888d24c6
JG
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 */
a58c490f
JG
135extern enum lttng_condition_status
136lttng_condition_buffer_usage_get_threshold(
137 const struct lttng_condition *condition,
138 uint64_t *threshold_bytes);
139
888d24c6
JG
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 */
a58c490f
JG
149extern enum lttng_condition_status
150lttng_condition_buffer_usage_set_threshold(
151 struct lttng_condition *condition,
152 uint64_t threshold_bytes);
153
888d24c6
JG
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 */
a58c490f
JG
166extern enum lttng_condition_status
167lttng_condition_buffer_usage_get_session_name(
168 const struct lttng_condition *condition,
169 const char **session_name);
170
888d24c6
JG
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 */
a58c490f
JG
179extern enum lttng_condition_status
180lttng_condition_buffer_usage_set_session_name(
181 struct lttng_condition *condition,
182 const char *session_name);
183
888d24c6
JG
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 */
a58c490f
JG
196extern enum lttng_condition_status
197lttng_condition_buffer_usage_get_channel_name(
198 const struct lttng_condition *condition,
199 const char **channel_name);
200
888d24c6
JG
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 */
a58c490f
JG
209extern enum lttng_condition_status
210lttng_condition_buffer_usage_set_channel_name(
211 struct lttng_condition *condition,
212 const char *channel_name);
213
888d24c6
JG
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 */
a58c490f
JG
222extern enum lttng_condition_status
223lttng_condition_buffer_usage_get_domain_type(
224 const struct lttng_condition *condition,
225 enum lttng_domain_type *type);
226
888d24c6
JG
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 */
a58c490f
JG
233extern enum lttng_condition_status
234lttng_condition_buffer_usage_set_domain_type(
235 struct lttng_condition *condition,
236 enum lttng_domain_type type);
237
238
888d24c6
JG
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 */
a58c490f
JG
256extern enum lttng_evaluation_status
257lttng_evaluation_buffer_usage_get_usage_ratio(
258 const struct lttng_evaluation *evaluation,
259 double *usage_ratio);
260
888d24c6
JG
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 */
a58c490f
JG
267extern enum lttng_evaluation_status
268lttng_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.034995 seconds and 5 git commands to generate.