Commit | Line | Data |
---|---|---|
3fd40f46 PP |
1 | #ifndef BABELTRACE2_LOGGING_H |
2 | #define BABELTRACE2_LOGGING_H | |
beb0fb75 PP |
3 | |
4 | /* | |
0dcb770f | 5 | * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation |
beb0fb75 PP |
6 | * |
7 | * Permission is hereby granted, free of charge, to any person obtaining a copy | |
8 | * of this software and associated documentation files (the "Software"), to deal | |
9 | * in the Software without restriction, including without limitation the rights | |
10 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | |
11 | * copies of the Software, and to permit persons to whom the Software is | |
12 | * furnished to do so, subject to the following conditions: | |
13 | * | |
14 | * The above copyright notice and this permission notice shall be included in | |
15 | * all copies or substantial portions of the Software. | |
16 | * | |
17 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
18 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
19 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |
20 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |
21 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
22 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | |
23 | * SOFTWARE. | |
24 | */ | |
25 | ||
9df34b44 PP |
26 | #ifndef __BT_IN_BABELTRACE_H |
27 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
28 | #endif | |
29 | ||
3fef1229 SM |
30 | #include <babeltrace2/logging-defs.h> |
31 | ||
beb0fb75 PP |
32 | #ifdef __cplusplus |
33 | extern "C" { | |
34 | #endif | |
35 | ||
7704a0af PP |
36 | /*! |
37 | @defgroup api-logging Logging | |
beb0fb75 | 38 | |
7704a0af PP |
39 | @brief |
40 | Logging level enumerators and library logging control. | |
41 | ||
42 | The logging API offers logging level enumerators (#bt_logging_level) | |
43 | as well as functions to control libbabeltrace2's internal logging. | |
44 | ||
45 | @note | |
46 | This API does \em not offer macros and functions to write logging | |
47 | statements: as of \bt_name_version_min_maj, the actual mechanism to | |
48 | log is implementation-defined for each user \bt_plugin. | |
49 | ||
50 | libbabeltrace2 contains many hundreds of logging statements to help you | |
51 | follow and debug your plugin or program. | |
52 | ||
53 | The library's initial logging level is controlled by the | |
54 | \c LIBBABELTRACE2_INIT_LOG_LEVEL environment variable. If this | |
55 | environment variable is not set at library load time, the library's | |
56 | initial logging level is #BT_LOGGING_LEVEL_NONE. See | |
57 | \ref api-fund-logging to learn more. | |
58 | ||
59 | Set libbabeltrace2's current logging level with | |
60 | bt_logging_set_global_level(). | |
61 | ||
62 | \anchor api-logging-extra-lib bt_logging_set_global_level() only | |
63 | controls <strong>libbabeltrace2</strong>'s logging level; it does \em | |
64 | not control the logging level of: | |
65 | ||
66 | - Individual \bt_p_comp: bt_graph_add_source_component(), | |
67 | bt_graph_add_source_component_with_initialize_method_data(), | |
68 | bt_graph_add_filter_component(), | |
69 | bt_graph_add_filter_component_with_initialize_method_data(), | |
70 | bt_graph_add_sink_component(), and | |
71 | bt_graph_add_sink_component_with_initialize_method_data() control | |
72 | this. | |
beb0fb75 | 73 | |
7704a0af PP |
74 | - A \ref api-qexec "query operation": |
75 | bt_query_executor_set_logging_level() controls this. | |
beb0fb75 | 76 | |
7704a0af PP |
77 | - The bt_get_greatest_operative_mip_version() operation: its |
78 | \bt_p{logging_level} parameter controls this. | |
beb0fb75 | 79 | |
7704a0af PP |
80 | As of \bt_name_version_min_maj, there's no module-specific logging level |
81 | control: bt_logging_set_global_level() sets the logging level of all the | |
82 | library's modules. | |
beb0fb75 | 83 | |
7704a0af PP |
84 | libbabeltrace2 writes its logging statements to the standard error |
85 | stream. A logging line looks like this: | |
86 | ||
87 | @code{.unparsed} | |
88 | 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0 | |
89 | @endcode | |
90 | ||
91 | See \ref api-fund-logging to learn more about the logging statement | |
92 | line's format. | |
93 | ||
94 | You can set a \em minimal logging level at the \bt_name project's build | |
95 | time (see \ref api-fund-logging to learn how). The logging statements | |
96 | with a level that's less severe than the minimal logging level are \em | |
97 | not built. For example, if the minimal logging level is | |
98 | #BT_LOGGING_LEVEL_INFO, the #BT_LOGGING_LEVEL_TRACE and | |
99 | #BT_LOGGING_LEVEL_DEBUG logging statements are not built. Use | |
100 | bt_logging_get_minimal_level() to get the library's minimal logging | |
101 | level. | |
beb0fb75 PP |
102 | */ |
103 | ||
7704a0af PP |
104 | /*! @{ */ |
105 | ||
106 | /*! | |
107 | @brief | |
108 | Logging level enumerators. | |
beb0fb75 | 109 | */ |
ee78f405 | 110 | typedef enum bt_logging_level { |
7704a0af PP |
111 | /*! |
112 | @brief | |
113 | \em TRACE level. | |
114 | ||
115 | Low-level debugging context information. | |
116 | ||
117 | The \em TRACE logging statements can significantly | |
118 | impact performance. | |
119 | */ | |
3fef1229 | 120 | BT_LOGGING_LEVEL_TRACE = __BT_LOGGING_LEVEL_TRACE, |
beb0fb75 | 121 | |
7704a0af PP |
122 | /*! |
123 | @brief | |
124 | \em DEBUG level. | |
125 | ||
126 | Debugging information, with a higher level of details than the | |
127 | \em TRACE level. | |
128 | ||
129 | The \em DEBUG logging statements do not significantly | |
130 | impact performance. | |
beb0fb75 | 131 | */ |
3fef1229 | 132 | BT_LOGGING_LEVEL_DEBUG = __BT_LOGGING_LEVEL_DEBUG, |
beb0fb75 | 133 | |
7704a0af PP |
134 | /*! |
135 | @brief | |
136 | \em INFO level. | |
137 | ||
138 | Informational messages that highlight progress or important | |
139 | states of the application, plugins, or library. | |
140 | ||
141 | The \em INFO logging statements do not significantly | |
142 | impact performance. | |
beb0fb75 | 143 | */ |
3fef1229 | 144 | BT_LOGGING_LEVEL_INFO = __BT_LOGGING_LEVEL_INFO, |
beb0fb75 | 145 | |
7704a0af PP |
146 | /*! |
147 | @brief | |
148 | \em WARNING level. | |
beb0fb75 | 149 | |
7704a0af PP |
150 | Unexpected situations which still allow the execution to |
151 | continue. | |
152 | ||
153 | The \em WARNING logging statements do not significantly | |
154 | impact performance. | |
beb0fb75 | 155 | */ |
3fef1229 | 156 | BT_LOGGING_LEVEL_WARNING = __BT_LOGGING_LEVEL_WARNING, |
beb0fb75 | 157 | |
7704a0af PP |
158 | /*! |
159 | @brief | |
160 | \em ERROR level. | |
161 | ||
162 | Errors that might still allow the execution to continue. | |
163 | ||
164 | Usually, once one or more errors are reported at this level, the | |
165 | application, plugin, or library won't perform any more useful | |
166 | task, but it should still exit cleanly. | |
167 | ||
168 | The \em ERROR logging statements do not significantly | |
169 | impact performance. | |
beb0fb75 | 170 | */ |
3fef1229 | 171 | BT_LOGGING_LEVEL_ERROR = __BT_LOGGING_LEVEL_ERROR, |
beb0fb75 | 172 | |
7704a0af PP |
173 | /*! |
174 | @brief | |
175 | \em FATAL level. | |
176 | ||
177 | Severe errors that lead the execution to abort immediately. | |
178 | ||
179 | The \em FATAL logging statements do not significantly | |
180 | impact performance. | |
beb0fb75 | 181 | */ |
3fef1229 | 182 | BT_LOGGING_LEVEL_FATAL = __BT_LOGGING_LEVEL_FATAL, |
beb0fb75 | 183 | |
7704a0af PP |
184 | /*! |
185 | @brief | |
186 | Logging is disabled. | |
187 | */ | |
3fef1229 | 188 | BT_LOGGING_LEVEL_NONE = __BT_LOGGING_LEVEL_NONE, |
ee78f405 | 189 | } bt_logging_level; |
beb0fb75 | 190 | |
7704a0af PP |
191 | /*! |
192 | @brief | |
193 | Sets the logging level of all the libbabeltrace2 modules to | |
194 | \bt_p{logging_level}. | |
beb0fb75 | 195 | |
7704a0af PP |
196 | The library's global logging level |
197 | \ref api-logging-extra-lib "does not affect" the logging level of | |
198 | individual components and query operations. | |
beb0fb75 | 199 | |
7704a0af PP |
200 | @param[in] logging_level |
201 | New library's global logging level. | |
beb0fb75 | 202 | |
7704a0af PP |
203 | @sa bt_logging_get_global_level() — |
204 | Returns the current library's global logging level. | |
beb0fb75 | 205 | */ |
7704a0af | 206 | extern void bt_logging_set_global_level(bt_logging_level logging_level); |
beb0fb75 | 207 | |
7704a0af PP |
208 | /*! |
209 | @brief | |
210 | Returns the current logging level of all the libbabeltrace2 modules. | |
beb0fb75 | 211 | |
7704a0af PP |
212 | @returns |
213 | Library's current global logging level. | |
beb0fb75 | 214 | |
7704a0af PP |
215 | @sa bt_logging_set_global_level() — |
216 | Sets the current library's global logging level. | |
beb0fb75 | 217 | */ |
ee78f405 | 218 | extern bt_logging_level bt_logging_get_global_level(void); |
beb0fb75 | 219 | |
7704a0af PP |
220 | /*! |
221 | @brief | |
222 | Returns the library's minimal (build-time) logging level. | |
223 | ||
224 | The library logging statements with a level that's less severe than the | |
225 | minimal logging level are \em not built. | |
beb0fb75 | 226 | |
7704a0af PP |
227 | For example, if the minimal logging level is #BT_LOGGING_LEVEL_INFO, the |
228 | #BT_LOGGING_LEVEL_TRACE and #BT_LOGGING_LEVEL_DEBUG logging statements | |
229 | are not built. | |
beb0fb75 | 230 | |
7704a0af PP |
231 | @returns |
232 | Library's minimal logging level. | |
beb0fb75 | 233 | |
7704a0af PP |
234 | @sa bt_logging_get_global_level() — |
235 | Returns the current library's global logging level. | |
beb0fb75 | 236 | */ |
7704a0af | 237 | extern bt_logging_level bt_logging_get_minimal_level(void); |
beb0fb75 | 238 | |
7704a0af | 239 | /*! @} */ |
beb0fb75 PP |
240 | |
241 | #ifdef __cplusplus | |
242 | } | |
243 | #endif | |
244 | ||
3fd40f46 | 245 | #endif /* BABELTRACE2_LOGGING_H */ |