Session consumed size notification
[lttng-tools.git] / include / lttng / condition / session-consumed-size.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_SESSION_CONSUMED_SIZE_H
19 #define LTTNG_CONDITION_SESSION_CONSUMED_SIZE_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 * Session consumed size conditions allow an action to be taken whenever a
35 * session's produced data size crosses a set threshold.
36 *
37 * These conditions are periodically evaluated against the current session
38 * statistics. The period at which these conditions are evaluated is
39 * governed by the channels' monitor timer.
40 *
41 * Session consumed size conditions have the following properties:
42 * - the exact name of the session to be monitored,
43 * - a total consumed size threshold, expressed in bytes.
44 *
45 * Wildcards, regular expressions or other globbing mechanisms are not supported
46 * in session consumed size condition properties.
47 */
48
49 /*
50 * Create a newly allocated session consumed size condition.
51 *
52 * A session consumed size condition evaluates to true whenever the sum of all
53 * its channels' consumed data size is higher than a set threshold. The
54 * consumed data sizes are free running counters.
55 *
56 * Returns a new condition on success, NULL on failure. This condition must be
57 * destroyed using lttng_condition_destroy().
58 */
59 extern struct lttng_condition *
60 lttng_condition_session_consumed_size_create(void);
61
62 /*
63 * Get the threshold of a session consumed size condition.
64 *
65 * The session consumed size condition's threshold must have been defined as
66 * an absolute value expressed in bytes in order for this call to succeed.
67 *
68 * Returns LTTNG_CONDITION_STATUS_OK on success and a threshold expressed in
69 * bytes, LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed, or
70 * LTTNG_CONDITION_STATUS_UNSET if a threshold, expressed as an absolute size in
71 * bytes, was not set prior to this call.
72 */
73 extern enum lttng_condition_status
74 lttng_condition_session_consumed_size_get_threshold(
75 const struct lttng_condition *condition,
76 uint64_t *consumed_threshold_bytes);
77
78 /*
79 * Set the threshold of a session consumed size usage condition.
80 *
81 * Setting a threshold overrides any previously set threshold.
82 *
83 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
84 * if invalid parameters are passed.
85 */
86 extern enum lttng_condition_status
87 lttng_condition_session_consumed_size_set_threshold(
88 struct lttng_condition *condition,
89 uint64_t consumed_threshold_bytes);
90
91 /*
92 * Get the session name property of a session consumed size condition.
93 *
94 * The caller does not assume the ownership of the returned session name. The
95 * session name shall only be used for the duration of the condition's
96 * lifetime, or before a different session name is set.
97 *
98 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's session
99 * name on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
100 * parameter is passed, or LTTNG_CONDITION_STATUS_UNSET if a session name
101 * was not set prior to this call.
102 */
103 extern enum lttng_condition_status
104 lttng_condition_session_consumed_size_get_session_name(
105 const struct lttng_condition *condition,
106 const char **session_name);
107
108 /*
109 * Set the session name property of a session consumed size condition.
110 *
111 * The passed session name parameter will be copied to the condition.
112 *
113 * Returns LTTNG_CONDITION_STATUS_OK on success, LTTNG_CONDITION_STATUS_INVALID
114 * if invalid parameters are passed.
115 */
116 extern enum lttng_condition_status
117 lttng_condition_session_consumed_size_set_session_name(
118 struct lttng_condition *condition,
119 const char *session_name);
120
121 /**
122 * lttng_evaluation_session_consumed_size is specialised lttng_evaluations
123 * which allow users to query a number of properties resulting from the
124 * evaluation of a condition which evaluated to true.
125 */
126
127 /*
128 * Get the session consumed property of a session consumed size evaluation.
129 *
130 * Returns LTTNG_CONDITION_STATUS_OK on success and a threshold expressed in
131 * bytes, or LTTNG_CONDITION_STATUS_INVALID if an invalid parameter is passed.
132 */
133 extern enum lttng_evaluation_status
134 lttng_evaluation_session_consumed_size_get_consumed_size(
135 const struct lttng_evaluation *evaluation,
136 uint64_t *session_consumed);
137
138 #ifdef __cplusplus
139 }
140 #endif
141
142 #endif /* LTTNG_CONDITION_SESSION_CONSUMED_SIZE_H */
This page took 0.058038 seconds and 5 git commands to generate.