Document libbabeltrace2's C API
[babeltrace.git] / include / babeltrace2 / logging.h
CommitLineData
3fd40f46
PP
1#ifndef BABELTRACE2_LOGGING_H
2#define BABELTRACE2_LOGGING_H
beb0fb75
PP
3
4/*
0dcb770f 5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
beb0fb75
PP
6 *
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:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
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
23 * SOFTWARE.
24 */
25
9df34b44
PP
26#ifndef __BT_IN_BABELTRACE_H
27# error "Please include <babeltrace2/babeltrace.h> instead."
28#endif
29
3fef1229
SM
30#include <babeltrace2/logging-defs.h>
31
beb0fb75
PP
32#ifdef __cplusplus
33extern "C" {
34#endif
35
7704a0af
PP
36/*!
37@defgroup api-logging Logging
beb0fb75 38
7704a0af
PP
39@brief
40 Logging level enumerators and library logging control.
41
42The logging API offers logging level enumerators (#bt_logging_level)
43as well as functions to control libbabeltrace2's internal logging.
44
45@note
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.
49
50libbabeltrace2 contains many hundreds of logging statements to help you
51follow and debug your plugin or program.
52
53The library's initial logging level is controlled by the
54\c LIBBABELTRACE2_INIT_LOG_LEVEL environment variable. If this
55environment variable is not set at library load time, the library's
56initial logging level is #BT_LOGGING_LEVEL_NONE. See
57\ref api-fund-logging to learn more.
58
59Set libbabeltrace2's current logging level with
60bt_logging_set_global_level().
61
62\anchor api-logging-extra-lib bt_logging_set_global_level() only
63controls <strong>libbabeltrace2</strong>'s logging level; it does \em
64not control the logging level of:
65
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
72 this.
beb0fb75 73
7704a0af
PP
74- A \ref api-qexec "query operation":
75 bt_query_executor_set_logging_level() controls this.
beb0fb75 76
7704a0af
PP
77- The bt_get_greatest_operative_mip_version() operation: its
78 \bt_p{logging_level} parameter controls this.
beb0fb75 79
7704a0af
PP
80As of \bt_name_version_min_maj, there's no module-specific logging level
81control: bt_logging_set_global_level() sets the logging level of all the
82library's modules.
beb0fb75 83
7704a0af
PP
84libbabeltrace2 writes its logging statements to the standard error
85stream. A logging line looks like this:
86
87@code{.unparsed}
8805-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
89@endcode
90
91See \ref api-fund-logging to learn more about the logging statement
92line's format.
93
94You can set a \em minimal logging level at the \bt_name project's build
95time (see \ref api-fund-logging to learn how). The logging statements
96with a level that's less severe than the minimal logging level are \em
97not 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
100bt_logging_get_minimal_level() to get the library's minimal logging
101level.
beb0fb75
PP
102*/
103
7704a0af
PP
104/*! @{ */
105
106/*!
107@brief
108 Logging level enumerators.
beb0fb75 109*/
ee78f405 110typedef enum bt_logging_level {
7704a0af
PP
111 /*!
112 @brief
113 \em TRACE level.
114
115 Low-level debugging context information.
116
117 The \em TRACE logging statements can significantly
118 impact performance.
119 */
3fef1229 120 BT_LOGGING_LEVEL_TRACE = __BT_LOGGING_LEVEL_TRACE,
beb0fb75 121
7704a0af
PP
122 /*!
123 @brief
124 \em DEBUG level.
125
126 Debugging information, with a higher level of details than the
127 \em TRACE level.
128
129 The \em DEBUG logging statements do not significantly
130 impact performance.
beb0fb75 131 */
3fef1229 132 BT_LOGGING_LEVEL_DEBUG = __BT_LOGGING_LEVEL_DEBUG,
beb0fb75 133
7704a0af
PP
134 /*!
135 @brief
136 \em INFO level.
137
138 Informational messages that highlight progress or important
139 states of the application, plugins, or library.
140
141 The \em INFO logging statements do not significantly
142 impact performance.
beb0fb75 143 */
3fef1229 144 BT_LOGGING_LEVEL_INFO = __BT_LOGGING_LEVEL_INFO,
beb0fb75 145
7704a0af
PP
146 /*!
147 @brief
148 \em WARNING level.
beb0fb75 149
7704a0af
PP
150 Unexpected situations which still allow the execution to
151 continue.
152
153 The \em WARNING logging statements do not significantly
154 impact performance.
beb0fb75 155 */
3fef1229 156 BT_LOGGING_LEVEL_WARNING = __BT_LOGGING_LEVEL_WARNING,
beb0fb75 157
7704a0af
PP
158 /*!
159 @brief
160 \em ERROR level.
161
162 Errors that might still allow the execution to continue.
163
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.
167
168 The \em ERROR logging statements do not significantly
169 impact performance.
beb0fb75 170 */
3fef1229 171 BT_LOGGING_LEVEL_ERROR = __BT_LOGGING_LEVEL_ERROR,
beb0fb75 172
7704a0af
PP
173 /*!
174 @brief
175 \em FATAL level.
176
177 Severe errors that lead the execution to abort immediately.
178
179 The \em FATAL logging statements do not significantly
180 impact performance.
beb0fb75 181 */
3fef1229 182 BT_LOGGING_LEVEL_FATAL = __BT_LOGGING_LEVEL_FATAL,
beb0fb75 183
7704a0af
PP
184 /*!
185 @brief
186 Logging is disabled.
187 */
3fef1229 188 BT_LOGGING_LEVEL_NONE = __BT_LOGGING_LEVEL_NONE,
ee78f405 189} bt_logging_level;
beb0fb75 190
7704a0af
PP
191/*!
192@brief
193 Sets the logging level of all the libbabeltrace2 modules to
194 \bt_p{logging_level}.
beb0fb75 195
7704a0af
PP
196The library's global logging level
197\ref api-logging-extra-lib "does not affect" the logging level of
198individual components and query operations.
beb0fb75 199
7704a0af
PP
200@param[in] logging_level
201 New library's global logging level.
beb0fb75 202
7704a0af
PP
203@sa bt_logging_get_global_level() &mdash;
204 Returns the current library's global logging level.
beb0fb75 205*/
7704a0af 206extern void bt_logging_set_global_level(bt_logging_level logging_level);
beb0fb75 207
7704a0af
PP
208/*!
209@brief
210 Returns the current logging level of all the libbabeltrace2 modules.
beb0fb75 211
7704a0af
PP
212@returns
213 Library's current global logging level.
beb0fb75 214
7704a0af
PP
215@sa bt_logging_set_global_level() &mdash;
216 Sets the current library's global logging level.
beb0fb75 217*/
ee78f405 218extern bt_logging_level bt_logging_get_global_level(void);
beb0fb75 219
7704a0af
PP
220/*!
221@brief
222 Returns the library's minimal (build-time) logging level.
223
224The library logging statements with a level that's less severe than the
225minimal logging level are \em not built.
beb0fb75 226
7704a0af
PP
227For example, if the minimal logging level is #BT_LOGGING_LEVEL_INFO, the
228#BT_LOGGING_LEVEL_TRACE and #BT_LOGGING_LEVEL_DEBUG logging statements
229are not built.
beb0fb75 230
7704a0af
PP
231@returns
232 Library's minimal logging level.
beb0fb75 233
7704a0af
PP
234@sa bt_logging_get_global_level() &mdash;
235 Returns the current library's global logging level.
beb0fb75 236*/
7704a0af 237extern bt_logging_level bt_logging_get_minimal_level(void);
beb0fb75 238
7704a0af 239/*! @} */
beb0fb75
PP
240
241#ifdef __cplusplus
242}
243#endif
244
3fd40f46 245#endif /* BABELTRACE2_LOGGING_H */
This page took 0.063319 seconds and 4 git commands to generate.