X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace2%2Flogging.h;h=2b5da45cecd584aa0e5bf9470c46c8bfee92a47b;hp=b6b89287f1a9be13c391b05543170165f45c8128;hb=0235b0db7de5bcacdb3650c92461f2ce5eb2143d;hpb=3fadfbc0c91f82c46bd36e6e0657ea93570c9db1 diff --git a/include/babeltrace2/logging.h b/include/babeltrace2/logging.h index b6b89287..2b5da45c 100644 --- a/include/babeltrace2/logging.h +++ b/include/babeltrace2/logging.h @@ -1,149 +1,229 @@ -#ifndef BABELTRACE_LOGGING_H -#define BABELTRACE_LOGGING_H - /* - * Copyright (c) 2017 Philippe Proulx - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. + * SPDX-License-Identifier: MIT * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. + * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation */ -#include -#include -#include +#ifndef BABELTRACE2_LOGGING_H +#define BABELTRACE2_LOGGING_H + +#ifndef __BT_IN_BABELTRACE_H +# error "Please include instead." +#endif + +#include #ifdef __cplusplus extern "C" { #endif -/** -@defgroup logging Logging -@ingroup apiref -@brief Logging. +/*! +@defgroup api-logging Logging -@code -#include -@endcode +@brief + Logging level enumerators and library logging control. + +The logging API offers logging level enumerators (#bt_logging_level) +as well as functions to control libbabeltrace2's internal logging. + +@note + This API does \em not offer macros and functions to write logging + statements: as of \bt_name_version_min_maj, the actual mechanism to + log is implementation-defined for each user \bt_plugin. -The functions in this module control the Babeltrace library's logging -behaviour. +libbabeltrace2 contains many hundreds of logging statements to help you +follow and debug your plugin or program. -You can set the current global log level of the library with -bt_logging_set_global_level(). Note that, if the level you set is below -the minimal logging level (configured at build time, which you can get -with bt_logging_get_minimal_level()), the logging statement between the -current global log level and the minimal log level are not executed. +The library's initial logging level is controlled by the +\c LIBBABELTRACE2_INIT_LOG_LEVEL environment variable. If this +environment variable is not set at library load time, the library's +initial logging level is #BT_LOGGING_LEVEL_NONE. See +\ref api-fund-logging to learn more. -@file -@brief Logging functions. -@sa logging +Set libbabeltrace2's current logging level with +bt_logging_set_global_level(). -@addtogroup logging -@{ +\anchor api-logging-extra-lib bt_logging_set_global_level() only +controls libbabeltrace2's logging level; it does \em +not control the logging level of: + +- Individual \bt_p_comp: bt_graph_add_source_component(), + bt_graph_add_source_component_with_initialize_method_data(), + bt_graph_add_filter_component(), + bt_graph_add_filter_component_with_initialize_method_data(), + bt_graph_add_sink_component(), and + bt_graph_add_sink_component_with_initialize_method_data() control + this. + +- A \ref api-qexec "query operation": + bt_query_executor_set_logging_level() controls this. + +- The bt_get_greatest_operative_mip_version() operation: its + \bt_p{logging_level} parameter controls this. + +As of \bt_name_version_min_maj, there's no module-specific logging level +control: bt_logging_set_global_level() sets the logging level of all the +library's modules. + +libbabeltrace2 writes its logging statements to the standard error +stream. A logging line looks like this: + +@code{.unparsed} +05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0 +@endcode + +See \ref api-fund-logging to learn more about the logging statement +line's format. + +You can set a \em minimal logging level at the \bt_name project's build +time (see \ref api-fund-logging to learn how). The logging statements +with a level that's less severe than the minimal logging level are \em +not built. For example, if the minimal logging level is +#BT_LOGGING_LEVEL_INFO, the #BT_LOGGING_LEVEL_TRACE and +#BT_LOGGING_LEVEL_DEBUG logging statements are not built. Use +bt_logging_get_minimal_level() to get the library's minimal logging +level. */ -/** -@brief Log levels. +/*! @{ */ + +/*! +@brief + Logging level enumerators. */ typedef enum bt_logging_level { - /// Additional, low-level debugging context information. - BT_LOGGING_LEVEL_VERBOSE = 1, + /*! + @brief + \em TRACE level. - /** - Debugging information, only useful when searching for the - cause of a bug. + Low-level debugging context information. + + The \em TRACE logging statements can significantly + impact performance. */ - BT_LOGGING_LEVEL_DEBUG = 2, + BT_LOGGING_LEVEL_TRACE = __BT_LOGGING_LEVEL_TRACE, + + /*! + @brief + \em DEBUG level. + + Debugging information, with a higher level of details than the + \em TRACE level. - /** - Non-debugging information and failure to load optional - subsystems. + The \em DEBUG logging statements do not significantly + impact performance. */ - BT_LOGGING_LEVEL_INFO = 3, + BT_LOGGING_LEVEL_DEBUG = __BT_LOGGING_LEVEL_DEBUG, - /** - Errors caused by a bad usage of the library, that is, a - non-observance of the documented function preconditions. + /*! + @brief + \em INFO level. - The library's and object's states remain consistent when a - warning is issued. + Informational messages that highlight progress or important + states of the application, plugins, or library. + + The \em INFO logging statements do not significantly + impact performance. */ - BT_LOGGING_LEVEL_WARN = 4, + BT_LOGGING_LEVEL_INFO = __BT_LOGGING_LEVEL_INFO, + + /*! + @brief + \em WARNING level. - /** - An important error from which the library cannot recover, but - the executed stack of functions can still return cleanly. + Unexpected situations which still allow the execution to + continue. + + The \em WARNING logging statements do not significantly + impact performance. */ - BT_LOGGING_LEVEL_ERROR = 5, + BT_LOGGING_LEVEL_WARNING = __BT_LOGGING_LEVEL_WARNING, + + /*! + @brief + \em ERROR level. + + Errors that might still allow the execution to continue. + + Usually, once one or more errors are reported at this level, the + application, plugin, or library won't perform any more useful + task, but it should still exit cleanly. - /** - The library cannot continue to work in this condition: it must - terminate immediately, without even returning to the user's - execution. + The \em ERROR logging statements do not significantly + impact performance. */ - BT_LOGGING_LEVEL_FATAL = 6, + BT_LOGGING_LEVEL_ERROR = __BT_LOGGING_LEVEL_ERROR, - /// Logging is disabled. - BT_LOGGING_LEVEL_NONE = 0xff, + /*! + @brief + \em FATAL level. + + Severe errors that lead the execution to abort immediately. + + The \em FATAL logging statements do not significantly + impact performance. + */ + BT_LOGGING_LEVEL_FATAL = __BT_LOGGING_LEVEL_FATAL, + + /*! + @brief + Logging is disabled. + */ + BT_LOGGING_LEVEL_NONE = __BT_LOGGING_LEVEL_NONE, } bt_logging_level; -/** -@brief Returns the minimal log level of the Babeltrace library. +/*! +@brief + Sets the logging level of all the libbabeltrace2 modules to + \bt_p{logging_level}. -The minimal log level is defined at the library's build time. Any -logging statement with a level below the minimal log level is not -compiled. This means that it is useless, although possible, to set the -global log level with bt_logging_set_global_level() below this level. +The library's global logging level +\ref api-logging-extra-lib "does not affect" the logging level of +individual components and query operations. -@returns Minimal, build time log level. +@param[in] logging_level + New library's global logging level. -@sa bt_logging_get_global_level(): Returns the current global log level. +@sa bt_logging_get_global_level() — + Returns the current library's global logging level. */ -extern bt_logging_level bt_logging_get_minimal_level(void); +extern void bt_logging_set_global_level(bt_logging_level logging_level); -/** -@brief Returns the current global log level of the Babeltrace library. +/*! +@brief + Returns the current logging level of all the libbabeltrace2 modules. -@returns Current global log level. +@returns + Library's current global logging level. -@sa bt_logging_set_global_level(): Sets the current global log level. -@sa bt_logging_get_minimal_level(): Returns the minimal log level. +@sa bt_logging_set_global_level() — + Sets the current library's global logging level. */ extern bt_logging_level bt_logging_get_global_level(void); -/** -@brief Sets the current global log level of the Babeltrace library - to \p log_level. +/*! +@brief + Returns the library's minimal (build-time) logging level. -If \p log_level is below what bt_logging_get_minimal_level() returns, -the logging statements with a level between \p log_level and the minimal -log level cannot be executed. +The library logging statements with a level that's less severe than the +minimal logging level are \em not built. -@param[in] log_level Library's new global log level. +For example, if the minimal logging level is #BT_LOGGING_LEVEL_INFO, the +#BT_LOGGING_LEVEL_TRACE and #BT_LOGGING_LEVEL_DEBUG logging statements +are not built. -@sa bt_logging_get_global_level(): Returns the global log level. +@returns + Library's minimal logging level. + +@sa bt_logging_get_global_level() — + Returns the current library's global logging level. */ -extern void bt_logging_set_global_level(bt_logging_level log_level); +extern bt_logging_level bt_logging_get_minimal_level(void); -/** @} */ +/*! @} */ #ifdef __cplusplus } #endif -#endif /* BABELTRACE_LOGGING_H */ +#endif /* BABELTRACE2_LOGGING_H */