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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
14 #include <babeltrace2/logging-defs.h>
21 @defgroup api-logging Logging
24 Logging level enumerators and library logging control.
26 The logging API offers logging level enumerators (#bt_logging_level)
27 as well as functions to control libbabeltrace2's internal logging.
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.
34 libbabeltrace2 contains many hundreds of logging statements to help you
35 follow and debug your plugin or program.
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.
43 Set libbabeltrace2's current logging level with
44 bt_logging_set_global_level().
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:
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
58 - A \ref api-qexec "query operation":
59 bt_query_executor_set_logging_level() controls this.
61 - The bt_get_greatest_operative_mip_version() operation: its
62 \bt_p{logging_level} parameter controls this.
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
68 libbabeltrace2 writes its logging statements to the standard error
69 stream. A logging line looks like this:
72 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
75 See \ref api-fund-logging to learn more about the logging statement
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
92 Logging level enumerators.
94 typedef enum bt_logging_level
{
99 Low-level debugging context information.
101 The \em TRACE logging statements can significantly
104 BT_LOGGING_LEVEL_TRACE
= __BT_LOGGING_LEVEL_TRACE
,
110 Debugging information, with a higher level of details than the
113 The \em DEBUG logging statements do not significantly
116 BT_LOGGING_LEVEL_DEBUG
= __BT_LOGGING_LEVEL_DEBUG
,
122 Informational messages that highlight progress or important
123 states of the application, plugins, or library.
125 The \em INFO logging statements do not significantly
128 BT_LOGGING_LEVEL_INFO
= __BT_LOGGING_LEVEL_INFO
,
134 Unexpected situations which still allow the execution to
137 The \em WARNING logging statements do not significantly
140 BT_LOGGING_LEVEL_WARNING
= __BT_LOGGING_LEVEL_WARNING
,
146 Errors that might still allow the execution to continue.
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.
152 The \em ERROR logging statements do not significantly
155 BT_LOGGING_LEVEL_ERROR
= __BT_LOGGING_LEVEL_ERROR
,
161 Severe errors that lead the execution to abort immediately.
163 The \em FATAL logging statements do not significantly
166 BT_LOGGING_LEVEL_FATAL
= __BT_LOGGING_LEVEL_FATAL
,
172 BT_LOGGING_LEVEL_NONE
= __BT_LOGGING_LEVEL_NONE
,
177 Sets the logging level of all the libbabeltrace2 modules to
178 \bt_p{logging_level}.
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.
184 @param[in] logging_level
185 New library's global logging level.
187 @sa bt_logging_get_global_level() —
188 Returns the current library's global logging level.
190 extern void bt_logging_set_global_level(bt_logging_level logging_level
);
194 Returns the current logging level of all the libbabeltrace2 modules.
197 Library's current global logging level.
199 @sa bt_logging_set_global_level() —
200 Sets the current library's global logging level.
202 extern bt_logging_level
bt_logging_get_global_level(void);
206 Returns the library's minimal (build-time) logging level.
208 The library logging statements with a level that's less severe than the
209 minimal logging level are \em not built.
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
216 Library's minimal logging level.
218 @sa bt_logging_get_global_level() —
219 Returns the current library's global logging level.
221 extern bt_logging_level
bt_logging_get_minimal_level(void);
229 #endif /* BABELTRACE2_LOGGING_H */