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() or
64 bt_get_greatest_operative_mip_version_with_restriction() operation:
65 its \bt_p{logging_level} parameter controls this.
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
71 libbabeltrace2 writes its logging statements to the standard error
72 stream. A logging line looks like this:
75 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
78 See \ref api-fund-logging to learn more about the logging statement
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
95 Logging level enumerators.
97 typedef enum bt_logging_level
{
102 Low-level debugging context information.
104 The \em TRACE logging statements can significantly
107 BT_LOGGING_LEVEL_TRACE
= __BT_LOGGING_LEVEL_TRACE
,
113 Debugging information, with a higher level of details than the
116 The \em DEBUG logging statements do not significantly
119 BT_LOGGING_LEVEL_DEBUG
= __BT_LOGGING_LEVEL_DEBUG
,
125 Informational messages that highlight progress or important
126 states of the application, plugins, or library.
128 The \em INFO logging statements do not significantly
131 BT_LOGGING_LEVEL_INFO
= __BT_LOGGING_LEVEL_INFO
,
137 Unexpected situations which still allow the execution to
140 The \em WARNING logging statements do not significantly
143 BT_LOGGING_LEVEL_WARNING
= __BT_LOGGING_LEVEL_WARNING
,
149 Errors that might still allow the execution to continue.
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.
155 The \em ERROR logging statements do not significantly
158 BT_LOGGING_LEVEL_ERROR
= __BT_LOGGING_LEVEL_ERROR
,
164 Severe errors that lead the execution to abort immediately.
166 The \em FATAL logging statements do not significantly
169 BT_LOGGING_LEVEL_FATAL
= __BT_LOGGING_LEVEL_FATAL
,
175 BT_LOGGING_LEVEL_NONE
= __BT_LOGGING_LEVEL_NONE
,
180 Sets the logging level of all the libbabeltrace2 modules to
181 \bt_p{logging_level}.
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.
187 @param[in] logging_level
188 New library's global logging level.
190 @sa bt_logging_get_global_level() —
191 Returns the current library's global logging level.
193 extern void bt_logging_set_global_level(bt_logging_level logging_level
)
198 Returns the current logging level of all the libbabeltrace2 modules.
201 Library's current global logging level.
203 @sa bt_logging_set_global_level() —
204 Sets the current library's global logging level.
206 extern bt_logging_level
bt_logging_get_global_level(void) __BT_NOEXCEPT
;
210 Returns the library's minimal (build-time) logging level.
212 The library logging statements with a level that's less severe than the
213 minimal logging level are \em not built.
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
220 Library's minimal logging level.
222 @sa bt_logging_get_global_level() —
223 Returns the current library's global logging level.
225 extern bt_logging_level
bt_logging_get_minimal_level(void) __BT_NOEXCEPT
;
233 #endif /* BABELTRACE2_LOGGING_H */