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 | |
8f351a15 MD |
63 | - The bt_get_greatest_operative_mip_version() or |
64 | bt_get_greatest_operative_mip_version_with_restriction() operation: | |
65 | its \bt_p{logging_level} parameter controls this. | |
beb0fb75 | 66 | |
43c59509 PP |
67 | As of \bt_name_version_min_maj, there's no module-specific logging level |
68 | control: bt_logging_set_global_level() sets the logging level of all the | |
69 | library's modules. | |
beb0fb75 | 70 | |
43c59509 PP |
71 | libbabeltrace2 writes its logging statements to the standard error |
72 | stream. A logging line looks like this: | |
73 | ||
74 | @code{.unparsed} | |
75 | 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0 | |
76 | @endcode | |
77 | ||
78 | See \ref api-fund-logging to learn more about the logging statement | |
79 | line's format. | |
80 | ||
81 | You can set a \em minimal logging level at the \bt_name project's build | |
82 | time (see \ref api-fund-logging to learn how). The logging statements | |
83 | with a level that's less severe than the minimal logging level are \em | |
84 | not built. For example, if the minimal logging level is | |
85 | #BT_LOGGING_LEVEL_INFO, the #BT_LOGGING_LEVEL_TRACE and | |
86 | #BT_LOGGING_LEVEL_DEBUG logging statements are not built. Use | |
87 | bt_logging_get_minimal_level() to get the library's minimal logging | |
88 | level. | |
beb0fb75 PP |
89 | */ |
90 | ||
43c59509 PP |
91 | /*! @{ */ |
92 | ||
93 | /*! | |
94 | @brief | |
95 | Logging level enumerators. | |
beb0fb75 | 96 | */ |
4cdfc5e8 | 97 | typedef enum bt_logging_level { |
43c59509 PP |
98 | /*! |
99 | @brief | |
100 | \em TRACE level. | |
101 | ||
102 | Low-level debugging context information. | |
103 | ||
104 | The \em TRACE logging statements can significantly | |
105 | impact performance. | |
106 | */ | |
9103e903 | 107 | BT_LOGGING_LEVEL_TRACE = __BT_LOGGING_LEVEL_TRACE, |
beb0fb75 | 108 | |
43c59509 PP |
109 | /*! |
110 | @brief | |
111 | \em DEBUG level. | |
112 | ||
113 | Debugging information, with a higher level of details than the | |
114 | \em TRACE level. | |
115 | ||
116 | The \em DEBUG logging statements do not significantly | |
117 | impact performance. | |
beb0fb75 | 118 | */ |
9103e903 | 119 | BT_LOGGING_LEVEL_DEBUG = __BT_LOGGING_LEVEL_DEBUG, |
beb0fb75 | 120 | |
43c59509 PP |
121 | /*! |
122 | @brief | |
123 | \em INFO level. | |
124 | ||
125 | Informational messages that highlight progress or important | |
126 | states of the application, plugins, or library. | |
127 | ||
128 | The \em INFO logging statements do not significantly | |
129 | impact performance. | |
beb0fb75 | 130 | */ |
9103e903 | 131 | BT_LOGGING_LEVEL_INFO = __BT_LOGGING_LEVEL_INFO, |
beb0fb75 | 132 | |
43c59509 PP |
133 | /*! |
134 | @brief | |
135 | \em WARNING level. | |
beb0fb75 | 136 | |
43c59509 PP |
137 | Unexpected situations which still allow the execution to |
138 | continue. | |
139 | ||
140 | The \em WARNING logging statements do not significantly | |
141 | impact performance. | |
beb0fb75 | 142 | */ |
9103e903 | 143 | BT_LOGGING_LEVEL_WARNING = __BT_LOGGING_LEVEL_WARNING, |
beb0fb75 | 144 | |
43c59509 PP |
145 | /*! |
146 | @brief | |
147 | \em ERROR level. | |
148 | ||
149 | Errors that might still allow the execution to continue. | |
150 | ||
151 | Usually, once one or more errors are reported at this level, the | |
152 | application, plugin, or library won't perform any more useful | |
153 | task, but it should still exit cleanly. | |
154 | ||
155 | The \em ERROR logging statements do not significantly | |
156 | impact performance. | |
beb0fb75 | 157 | */ |
9103e903 | 158 | BT_LOGGING_LEVEL_ERROR = __BT_LOGGING_LEVEL_ERROR, |
beb0fb75 | 159 | |
43c59509 PP |
160 | /*! |
161 | @brief | |
162 | \em FATAL level. | |
163 | ||
164 | Severe errors that lead the execution to abort immediately. | |
165 | ||
166 | The \em FATAL logging statements do not significantly | |
167 | impact performance. | |
beb0fb75 | 168 | */ |
9103e903 | 169 | BT_LOGGING_LEVEL_FATAL = __BT_LOGGING_LEVEL_FATAL, |
beb0fb75 | 170 | |
43c59509 PP |
171 | /*! |
172 | @brief | |
173 | Logging is disabled. | |
174 | */ | |
9103e903 | 175 | BT_LOGGING_LEVEL_NONE = __BT_LOGGING_LEVEL_NONE, |
4cdfc5e8 | 176 | } bt_logging_level; |
beb0fb75 | 177 | |
43c59509 PP |
178 | /*! |
179 | @brief | |
180 | Sets the logging level of all the libbabeltrace2 modules to | |
181 | \bt_p{logging_level}. | |
beb0fb75 | 182 | |
43c59509 PP |
183 | The library's global logging level |
184 | \ref api-logging-extra-lib "does not affect" the logging level of | |
185 | individual components and query operations. | |
beb0fb75 | 186 | |
43c59509 PP |
187 | @param[in] logging_level |
188 | New library's global logging level. | |
beb0fb75 | 189 | |
43c59509 PP |
190 | @sa bt_logging_get_global_level() — |
191 | Returns the current library's global logging level. | |
beb0fb75 | 192 | */ |
4c81a2b7 PP |
193 | extern void bt_logging_set_global_level(bt_logging_level logging_level) |
194 | __BT_NOEXCEPT; | |
beb0fb75 | 195 | |
43c59509 PP |
196 | /*! |
197 | @brief | |
198 | Returns the current logging level of all the libbabeltrace2 modules. | |
beb0fb75 | 199 | |
43c59509 PP |
200 | @returns |
201 | Library's current global logging level. | |
beb0fb75 | 202 | |
43c59509 PP |
203 | @sa bt_logging_set_global_level() — |
204 | Sets the current library's global logging level. | |
beb0fb75 | 205 | */ |
4c81a2b7 | 206 | extern bt_logging_level bt_logging_get_global_level(void) __BT_NOEXCEPT; |
beb0fb75 | 207 | |
43c59509 PP |
208 | /*! |
209 | @brief | |
210 | Returns the library's minimal (build-time) logging level. | |
211 | ||
212 | The library logging statements with a level that's less severe than the | |
213 | minimal logging level are \em not built. | |
beb0fb75 | 214 | |
43c59509 PP |
215 | For example, if the minimal logging level is #BT_LOGGING_LEVEL_INFO, the |
216 | #BT_LOGGING_LEVEL_TRACE and #BT_LOGGING_LEVEL_DEBUG logging statements | |
217 | are not built. | |
beb0fb75 | 218 | |
43c59509 PP |
219 | @returns |
220 | Library's minimal logging level. | |
beb0fb75 | 221 | |
43c59509 PP |
222 | @sa bt_logging_get_global_level() — |
223 | Returns the current library's global logging level. | |
beb0fb75 | 224 | */ |
4c81a2b7 | 225 | extern bt_logging_level bt_logging_get_minimal_level(void) __BT_NOEXCEPT; |
beb0fb75 | 226 | |
43c59509 | 227 | /*! @} */ |
beb0fb75 PP |
228 | |
229 | #ifdef __cplusplus | |
230 | } | |
231 | #endif | |
232 | ||
924dc299 | 233 | #endif /* BABELTRACE2_LOGGING_H */ |