include/babeltrace2/logging.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_LOGGING_H
   8 #define BABELTRACE2_LOGGING_H
   9
  10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
  11
  12 #ifndef __BT_IN_BABELTRACE_H
  13 # error "Please include <babeltrace2/babeltrace.h> instead."
  14 #endif
  15
  16 #include <babeltrace2/logging-defs.h>
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 /*!
  23 @defgroup api-logging Logging
  24
  25 @brief
  26     Logging level enumerators and library logging control.
  27
  28 The logging API offers logging level enumerators (#bt_logging_level)
  29 as well as functions to control libbabeltrace2's internal logging.
  30
  31 @note
  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.
  35
  36 libbabeltrace2 contains many hundreds of logging statements to help you
  37 follow and debug your plugin or program.
  38
  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.
  44
  45 Set libbabeltrace2's current logging level with
  46 bt_logging_set_global_level().
  47
  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:
  51
  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
  58   this.
  59
  60 - A \ref api-qexec "query operation":
  61   bt_query_executor_set_logging_level() controls this.
  62
  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.
  66
  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
  69 library's modules.
  70
  71 libbabeltrace2 writes its logging statements to the standard error
  72 stream. A logging line looks like this:
  73
  74 @code{.unparsed}
  75 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
  76 @endcode
  77
  78 See \ref api-fund-logging to learn more about the logging statement
  79 line's format.
  80
  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
  88 level.
  89 */
  90
  91 /*! @{ */
  92
  93 /*!
  94 @brief
  95     Logging level enumerators.
  96 */
  97 typedef enum bt_logging_level {
  98         /*!
  99         @brief
 100             \em TRACE level.
 101
 102         Low-level debugging context information.
 103
 104         The \em TRACE logging statements can significantly
 105         impact performance.
 106         */
 107         BT_LOGGING_LEVEL_TRACE          = __BT_LOGGING_LEVEL_TRACE,
 108
 109         /*!
 110         @brief
 111             \em DEBUG level.
 112
 113         Debugging information, with a higher level of details than the
 114         \em TRACE level.
 115
 116         The \em DEBUG logging statements do not significantly
 117         impact performance.
 118         */
 119         BT_LOGGING_LEVEL_DEBUG          = __BT_LOGGING_LEVEL_DEBUG,
 120
 121         /*!
 122         @brief
 123             \em INFO level.
 124
 125         Informational messages that highlight progress or important
 126         states of the application, plugins, or library.
 127
 128         The \em INFO logging statements do not significantly
 129         impact performance.
 130         */
 131         BT_LOGGING_LEVEL_INFO           = __BT_LOGGING_LEVEL_INFO,
 132
 133         /*!
 134         @brief
 135             \em WARNING level.
 136
 137         Unexpected situations which still allow the execution to
 138         continue.
 139
 140         The \em WARNING logging statements do not significantly
 141         impact performance.
 142         */
 143         BT_LOGGING_LEVEL_WARNING        = __BT_LOGGING_LEVEL_WARNING,
 144
 145         /*!
 146         @brief
 147             \em ERROR level.
 148
 149         Errors that might still allow the execution to continue.
 150
 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.
 154
 155         The \em ERROR logging statements do not significantly
 156         impact performance.
 157         */
 158         BT_LOGGING_LEVEL_ERROR          = __BT_LOGGING_LEVEL_ERROR,
 159
 160         /*!
 161         @brief
 162             \em FATAL level.
 163
 164         Severe errors that lead the execution to abort immediately.
 165
 166         The \em FATAL logging statements do not significantly
 167         impact performance.
 168         */
 169         BT_LOGGING_LEVEL_FATAL          = __BT_LOGGING_LEVEL_FATAL,
 170
 171         /*!
 172         @brief
 173             Logging is disabled.
 174         */
 175         BT_LOGGING_LEVEL_NONE           = __BT_LOGGING_LEVEL_NONE,
 176 } bt_logging_level;
 177
 178 /*!
 179 @brief
 180     Sets the logging level of all the libbabeltrace2 modules to
 181     \bt_p{logging_level}.
 182
 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.
 186
 187 @param[in] logging_level
 188     New library's global logging level.
 189
 190 @sa bt_logging_get_global_level() &mdash;
 191     Returns the current library's global logging level.
 192 */
 193 extern void bt_logging_set_global_level(bt_logging_level logging_level)
 194                 __BT_NOEXCEPT;
 195
 196 /*!
 197 @brief
 198     Returns the current logging level of all the libbabeltrace2 modules.
 199
 200 @returns
 201     Library's current global logging level.
 202
 203 @sa bt_logging_set_global_level() &mdash;
 204     Sets the current library's global logging level.
 205 */
 206 extern bt_logging_level bt_logging_get_global_level(void) __BT_NOEXCEPT;
 207
 208 /*!
 209 @brief
 210     Returns the library's minimal (build-time) logging level.
 211
 212 The library logging statements with a level that's less severe than the
 213 minimal logging level are \em not built.
 214
 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
 217 are not built.
 218
 219 @returns
 220     Library's minimal logging level.
 221
 222 @sa bt_logging_get_global_level() &mdash;
 223     Returns the current library's global logging level.
 224 */
 225 extern bt_logging_level bt_logging_get_minimal_level(void) __BT_NOEXCEPT;
 226
 227 /*! @} */
 228
 229 #ifdef __cplusplus
 230 }
 231 #endif
 232
 233 #endif /* BABELTRACE2_LOGGING_H */