Commit | Line | Data |
---|---|---|
beb0fb75 | 1 | /* |
0235b0db | 2 | * SPDX-License-Identifier: MIT |
beb0fb75 | 3 | * |
0235b0db | 4 | * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation |
beb0fb75 PP |
5 | */ |
6 | ||
0235b0db MJ |
7 | #ifndef BABELTRACE2_LOGGING_H |
8 | #define BABELTRACE2_LOGGING_H | |
9 | ||
f38da6ca SM |
10 | /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */ |
11 | ||
4fa90f32 PP |
12 | #ifndef __BT_IN_BABELTRACE_H |
13 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
14 | #endif | |
15 | ||
9103e903 SM |
16 | #include <babeltrace2/logging-defs.h> |
17 | ||
beb0fb75 PP |
18 | #ifdef __cplusplus |
19 | extern "C" { | |
20 | #endif | |
21 | ||
43c59509 PP |
22 | /*! |
23 | @defgroup api-logging Logging | |
beb0fb75 | 24 | |
43c59509 PP |
25 | @brief |
26 | Logging level enumerators and library logging control. | |
27 | ||
28 | The logging API offers logging level enumerators (#bt_logging_level) | |
29 | as well as functions to control libbabeltrace2's internal logging. | |
30 | ||
31 | @note | |
32 | This API does \em not offer macros and functions to write logging | |
33 | statements: as of \bt_name_version_min_maj, the actual mechanism to | |
34 | log is implementation-defined for each user \bt_plugin. | |
35 | ||
36 | libbabeltrace2 contains many hundreds of logging statements to help you | |
37 | follow and debug your plugin or program. | |
38 | ||
39 | The library's initial logging level is controlled by the | |
40 | \c LIBBABELTRACE2_INIT_LOG_LEVEL environment variable. If this | |
41 | environment variable is not set at library load time, the library's | |
42 | initial logging level is #BT_LOGGING_LEVEL_NONE. See | |
43 | \ref api-fund-logging to learn more. | |
44 | ||
45 | Set libbabeltrace2's current logging level with | |
46 | bt_logging_set_global_level(). | |
47 | ||
48 | \anchor api-logging-extra-lib bt_logging_set_global_level() only | |
49 | controls <strong>libbabeltrace2</strong>'s logging level; it does \em | |
50 | not control the logging level of: | |
51 | ||
52 | - Individual \bt_p_comp: bt_graph_add_source_component(), | |
53 | bt_graph_add_source_component_with_initialize_method_data(), | |
54 | bt_graph_add_filter_component(), | |
55 | bt_graph_add_filter_component_with_initialize_method_data(), | |
56 | bt_graph_add_sink_component(), and | |
57 | bt_graph_add_sink_component_with_initialize_method_data() control | |
58 | this. | |
beb0fb75 | 59 | |
43c59509 PP |
60 | - A \ref api-qexec "query operation": |
61 | bt_query_executor_set_logging_level() controls this. | |
beb0fb75 | 62 | |
43c59509 PP |
63 | - The bt_get_greatest_operative_mip_version() operation: its |
64 | \bt_p{logging_level} parameter controls this. | |
beb0fb75 | 65 | |
43c59509 PP |
66 | As of \bt_name_version_min_maj, there's no module-specific logging level |
67 | control: bt_logging_set_global_level() sets the logging level of all the | |
68 | library's modules. | |
beb0fb75 | 69 | |
43c59509 PP |
70 | libbabeltrace2 writes its logging statements to the standard error |
71 | stream. A logging line looks like this: | |
72 | ||
73 | @code{.unparsed} | |
74 | 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0 | |
75 | @endcode | |
76 | ||
77 | See \ref api-fund-logging to learn more about the logging statement | |
78 | line's format. | |
79 | ||
80 | You can set a \em minimal logging level at the \bt_name project's build | |
81 | time (see \ref api-fund-logging to learn how). The logging statements | |
82 | with a level that's less severe than the minimal logging level are \em | |
83 | not built. For example, if the minimal logging level is | |
84 | #BT_LOGGING_LEVEL_INFO, the #BT_LOGGING_LEVEL_TRACE and | |
85 | #BT_LOGGING_LEVEL_DEBUG logging statements are not built. Use | |
86 | bt_logging_get_minimal_level() to get the library's minimal logging | |
87 | level. | |
beb0fb75 PP |
88 | */ |
89 | ||
43c59509 PP |
90 | /*! @{ */ |
91 | ||
92 | /*! | |
93 | @brief | |
94 | Logging level enumerators. | |
beb0fb75 | 95 | */ |
4cdfc5e8 | 96 | typedef enum bt_logging_level { |
43c59509 PP |
97 | /*! |
98 | @brief | |
99 | \em TRACE level. | |
100 | ||
101 | Low-level debugging context information. | |
102 | ||
103 | The \em TRACE logging statements can significantly | |
104 | impact performance. | |
105 | */ | |
9103e903 | 106 | BT_LOGGING_LEVEL_TRACE = __BT_LOGGING_LEVEL_TRACE, |
beb0fb75 | 107 | |
43c59509 PP |
108 | /*! |
109 | @brief | |
110 | \em DEBUG level. | |
111 | ||
112 | Debugging information, with a higher level of details than the | |
113 | \em TRACE level. | |
114 | ||
115 | The \em DEBUG logging statements do not significantly | |
116 | impact performance. | |
beb0fb75 | 117 | */ |
9103e903 | 118 | BT_LOGGING_LEVEL_DEBUG = __BT_LOGGING_LEVEL_DEBUG, |
beb0fb75 | 119 | |
43c59509 PP |
120 | /*! |
121 | @brief | |
122 | \em INFO level. | |
123 | ||
124 | Informational messages that highlight progress or important | |
125 | states of the application, plugins, or library. | |
126 | ||
127 | The \em INFO logging statements do not significantly | |
128 | impact performance. | |
beb0fb75 | 129 | */ |
9103e903 | 130 | BT_LOGGING_LEVEL_INFO = __BT_LOGGING_LEVEL_INFO, |
beb0fb75 | 131 | |
43c59509 PP |
132 | /*! |
133 | @brief | |
134 | \em WARNING level. | |
beb0fb75 | 135 | |
43c59509 PP |
136 | Unexpected situations which still allow the execution to |
137 | continue. | |
138 | ||
139 | The \em WARNING logging statements do not significantly | |
140 | impact performance. | |
beb0fb75 | 141 | */ |
9103e903 | 142 | BT_LOGGING_LEVEL_WARNING = __BT_LOGGING_LEVEL_WARNING, |
beb0fb75 | 143 | |
43c59509 PP |
144 | /*! |
145 | @brief | |
146 | \em ERROR level. | |
147 | ||
148 | Errors that might still allow the execution to continue. | |
149 | ||
150 | Usually, once one or more errors are reported at this level, the | |
151 | application, plugin, or library won't perform any more useful | |
152 | task, but it should still exit cleanly. | |
153 | ||
154 | The \em ERROR logging statements do not significantly | |
155 | impact performance. | |
beb0fb75 | 156 | */ |
9103e903 | 157 | BT_LOGGING_LEVEL_ERROR = __BT_LOGGING_LEVEL_ERROR, |
beb0fb75 | 158 | |
43c59509 PP |
159 | /*! |
160 | @brief | |
161 | \em FATAL level. | |
162 | ||
163 | Severe errors that lead the execution to abort immediately. | |
164 | ||
165 | The \em FATAL logging statements do not significantly | |
166 | impact performance. | |
beb0fb75 | 167 | */ |
9103e903 | 168 | BT_LOGGING_LEVEL_FATAL = __BT_LOGGING_LEVEL_FATAL, |
beb0fb75 | 169 | |
43c59509 PP |
170 | /*! |
171 | @brief | |
172 | Logging is disabled. | |
173 | */ | |
9103e903 | 174 | BT_LOGGING_LEVEL_NONE = __BT_LOGGING_LEVEL_NONE, |
4cdfc5e8 | 175 | } bt_logging_level; |
beb0fb75 | 176 | |
43c59509 PP |
177 | /*! |
178 | @brief | |
179 | Sets the logging level of all the libbabeltrace2 modules to | |
180 | \bt_p{logging_level}. | |
beb0fb75 | 181 | |
43c59509 PP |
182 | The library's global logging level |
183 | \ref api-logging-extra-lib "does not affect" the logging level of | |
184 | individual components and query operations. | |
beb0fb75 | 185 | |
43c59509 PP |
186 | @param[in] logging_level |
187 | New library's global logging level. | |
beb0fb75 | 188 | |
43c59509 PP |
189 | @sa bt_logging_get_global_level() — |
190 | Returns the current library's global logging level. | |
beb0fb75 | 191 | */ |
4c81a2b7 PP |
192 | extern void bt_logging_set_global_level(bt_logging_level logging_level) |
193 | __BT_NOEXCEPT; | |
beb0fb75 | 194 | |
43c59509 PP |
195 | /*! |
196 | @brief | |
197 | Returns the current logging level of all the libbabeltrace2 modules. | |
beb0fb75 | 198 | |
43c59509 PP |
199 | @returns |
200 | Library's current global logging level. | |
beb0fb75 | 201 | |
43c59509 PP |
202 | @sa bt_logging_set_global_level() — |
203 | Sets the current library's global logging level. | |
beb0fb75 | 204 | */ |
4c81a2b7 | 205 | extern bt_logging_level bt_logging_get_global_level(void) __BT_NOEXCEPT; |
beb0fb75 | 206 | |
43c59509 PP |
207 | /*! |
208 | @brief | |
209 | Returns the library's minimal (build-time) logging level. | |
210 | ||
211 | The library logging statements with a level that's less severe than the | |
212 | minimal logging level are \em not built. | |
beb0fb75 | 213 | |
43c59509 PP |
214 | For example, if the minimal logging level is #BT_LOGGING_LEVEL_INFO, the |
215 | #BT_LOGGING_LEVEL_TRACE and #BT_LOGGING_LEVEL_DEBUG logging statements | |
216 | are not built. | |
beb0fb75 | 217 | |
43c59509 PP |
218 | @returns |
219 | Library's minimal logging level. | |
beb0fb75 | 220 | |
43c59509 PP |
221 | @sa bt_logging_get_global_level() — |
222 | Returns the current library's global logging level. | |
beb0fb75 | 223 | */ |
4c81a2b7 | 224 | extern bt_logging_level bt_logging_get_minimal_level(void) __BT_NOEXCEPT; |
beb0fb75 | 225 | |
43c59509 | 226 | /*! @} */ |
beb0fb75 PP |
227 | |
228 | #ifdef __cplusplus | |
229 | } | |
230 | #endif | |
231 | ||
924dc299 | 232 | #endif /* BABELTRACE2_LOGGING_H */ |