1 #ifndef BABELTRACE2_LOGGING_H
2 #define BABELTRACE2_LOGGING_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
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:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
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
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
30 #include <babeltrace2/logging-defs.h>
37 @defgroup api-logging Logging
40 Logging level enumerators and library logging control.
42 The logging API offers logging level enumerators (#bt_logging_level)
43 as well as functions to control libbabeltrace2's internal logging.
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.
50 libbabeltrace2 contains many hundreds of logging statements to help you
51 follow and debug your plugin or program.
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.
59 Set libbabeltrace2's current logging level with
60 bt_logging_set_global_level().
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:
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
74 - A \ref api-qexec "query operation":
75 bt_query_executor_set_logging_level() controls this.
77 - The bt_get_greatest_operative_mip_version() operation: its
78 \bt_p{logging_level} parameter controls this.
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
84 libbabeltrace2 writes its logging statements to the standard error
85 stream. A logging line looks like this:
88 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
91 See \ref api-fund-logging to learn more about the logging statement
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
108 Logging level enumerators.
110 typedef enum bt_logging_level
{
115 Low-level debugging context information.
117 The \em TRACE logging statements can significantly
120 BT_LOGGING_LEVEL_TRACE
= __BT_LOGGING_LEVEL_TRACE
,
126 Debugging information, with a higher level of details than the
129 The \em DEBUG logging statements do not significantly
132 BT_LOGGING_LEVEL_DEBUG
= __BT_LOGGING_LEVEL_DEBUG
,
138 Informational messages that highlight progress or important
139 states of the application, plugins, or library.
141 The \em INFO logging statements do not significantly
144 BT_LOGGING_LEVEL_INFO
= __BT_LOGGING_LEVEL_INFO
,
150 Unexpected situations which still allow the execution to
153 The \em WARNING logging statements do not significantly
156 BT_LOGGING_LEVEL_WARNING
= __BT_LOGGING_LEVEL_WARNING
,
162 Errors that might still allow the execution to continue.
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.
168 The \em ERROR logging statements do not significantly
171 BT_LOGGING_LEVEL_ERROR
= __BT_LOGGING_LEVEL_ERROR
,
177 Severe errors that lead the execution to abort immediately.
179 The \em FATAL logging statements do not significantly
182 BT_LOGGING_LEVEL_FATAL
= __BT_LOGGING_LEVEL_FATAL
,
188 BT_LOGGING_LEVEL_NONE
= __BT_LOGGING_LEVEL_NONE
,
193 Sets the logging level of all the libbabeltrace2 modules to
194 \bt_p{logging_level}.
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.
200 @param[in] logging_level
201 New library's global logging level.
203 @sa bt_logging_get_global_level() —
204 Returns the current library's global logging level.
206 extern void bt_logging_set_global_level(bt_logging_level logging_level
);
210 Returns the current logging level of all the libbabeltrace2 modules.
213 Library's current global logging level.
215 @sa bt_logging_set_global_level() —
216 Sets the current library's global logging level.
218 extern bt_logging_level
bt_logging_get_global_level(void);
222 Returns the library's minimal (build-time) logging level.
224 The library logging statements with a level that's less severe than the
225 minimal logging level are \em not built.
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
232 Library's minimal logging level.
234 @sa bt_logging_get_global_level() —
235 Returns the current library's global logging level.
237 extern bt_logging_level
bt_logging_get_minimal_level(void);
245 #endif /* BABELTRACE2_LOGGING_H */