2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_LOGGING_H
8 #define BABELTRACE2_LOGGING_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/logging-defs.h>
23 @defgroup api-logging Logging
26 Logging level enumerators and library logging control.
28 The logging API offers logging level enumerators (#bt_logging_level)
29 as well as functions to control libbabeltrace2's internal logging.
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.
36 libbabeltrace2 contains many hundreds of logging statements to help you
37 follow and debug your plugin or program.
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.
45 Set libbabeltrace2's current logging level with
46 bt_logging_set_global_level().
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:
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
60 - A \ref api-qexec "query operation":
61 bt_query_executor_set_logging_level() controls this.
63 - The bt_get_greatest_operative_mip_version() operation: its
64 \bt_p{logging_level} parameter controls this.
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
70 libbabeltrace2 writes its logging statements to the standard error
71 stream. A logging line looks like this:
74 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
77 See \ref api-fund-logging to learn more about the logging statement
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
94 Logging level enumerators.
96 typedef enum bt_logging_level
{
101 Low-level debugging context information.
103 The \em TRACE logging statements can significantly
106 BT_LOGGING_LEVEL_TRACE
= __BT_LOGGING_LEVEL_TRACE
,
112 Debugging information, with a higher level of details than the
115 The \em DEBUG logging statements do not significantly
118 BT_LOGGING_LEVEL_DEBUG
= __BT_LOGGING_LEVEL_DEBUG
,
124 Informational messages that highlight progress or important
125 states of the application, plugins, or library.
127 The \em INFO logging statements do not significantly
130 BT_LOGGING_LEVEL_INFO
= __BT_LOGGING_LEVEL_INFO
,
136 Unexpected situations which still allow the execution to
139 The \em WARNING logging statements do not significantly
142 BT_LOGGING_LEVEL_WARNING
= __BT_LOGGING_LEVEL_WARNING
,
148 Errors that might still allow the execution to continue.
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.
154 The \em ERROR logging statements do not significantly
157 BT_LOGGING_LEVEL_ERROR
= __BT_LOGGING_LEVEL_ERROR
,
163 Severe errors that lead the execution to abort immediately.
165 The \em FATAL logging statements do not significantly
168 BT_LOGGING_LEVEL_FATAL
= __BT_LOGGING_LEVEL_FATAL
,
174 BT_LOGGING_LEVEL_NONE
= __BT_LOGGING_LEVEL_NONE
,
179 Sets the logging level of all the libbabeltrace2 modules to
180 \bt_p{logging_level}.
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.
186 @param[in] logging_level
187 New library's global logging level.
189 @sa bt_logging_get_global_level() —
190 Returns the current library's global logging level.
192 extern void bt_logging_set_global_level(bt_logging_level logging_level
)
197 Returns the current logging level of all the libbabeltrace2 modules.
200 Library's current global logging level.
202 @sa bt_logging_set_global_level() —
203 Sets the current library's global logging level.
205 extern bt_logging_level
bt_logging_get_global_level(void) __BT_NOEXCEPT
;
209 Returns the library's minimal (build-time) logging level.
211 The library logging statements with a level that's less severe than the
212 minimal logging level are \em not built.
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
219 Library's minimal logging level.
221 @sa bt_logging_get_global_level() —
222 Returns the current library's global logging level.
224 extern bt_logging_level
bt_logging_get_minimal_level(void) __BT_NOEXCEPT
;
232 #endif /* BABELTRACE2_LOGGING_H */