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