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() operation: its
  64   \bt_p{logging_level} parameter controls this.
  65
  66 As of \bt_name_version_min_maj, there's no module-specific logging level
  67 control: bt_logging_set_global_level() sets the logging level of all the
  68 library's modules.
  69
  70 libbabeltrace2 writes its logging statements to the standard error
  71 stream. A logging line looks like this:
  72
  73 @code{.unparsed}
  74 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
  75 @endcode
  76
  77 See \ref api-fund-logging to learn more about the logging statement
  78 line's format.
  79
  80 You can set a \em minimal logging level at the \bt_name project's build
  81 time (see \ref api-fund-logging to learn how). The logging statements
  82 with a level that's less severe than the minimal logging level are \em
  83 not built. For example, if the minimal logging level is
  84 #BT_LOGGING_LEVEL_INFO, the #BT_LOGGING_LEVEL_TRACE and
  85 #BT_LOGGING_LEVEL_DEBUG logging statements are not built. Use
  86 bt_logging_get_minimal_level() to get the library's minimal logging
  87 level.
  88 */
  89
  90 /*! @{ */
  91
  92 /*!
  93 @brief
  94     Logging level enumerators.
  95 */
  96 typedef enum bt_logging_level {
  97         /*!
  98         @brief
  99             \em TRACE level.
 100
 101         Low-level debugging context information.
 102
 103         The \em TRACE logging statements can significantly
 104         impact performance.
 105         */
 106         BT_LOGGING_LEVEL_TRACE          = __BT_LOGGING_LEVEL_TRACE,
 107
 108         /*!
 109         @brief
 110             \em DEBUG level.
 111
 112         Debugging information, with a higher level of details than the
 113         \em TRACE level.
 114
 115         The \em DEBUG logging statements do not significantly
 116         impact performance.
 117         */
 118         BT_LOGGING_LEVEL_DEBUG          = __BT_LOGGING_LEVEL_DEBUG,
 119
 120         /*!
 121         @brief
 122             \em INFO level.
 123
 124         Informational messages that highlight progress or important
 125         states of the application, plugins, or library.
 126
 127         The \em INFO logging statements do not significantly
 128         impact performance.
 129         */
 130         BT_LOGGING_LEVEL_INFO           = __BT_LOGGING_LEVEL_INFO,
 131
 132         /*!
 133         @brief
 134             \em WARNING level.
 135
 136         Unexpected situations which still allow the execution to
 137         continue.
 138
 139         The \em WARNING logging statements do not significantly
 140         impact performance.
 141         */
 142         BT_LOGGING_LEVEL_WARNING        = __BT_LOGGING_LEVEL_WARNING,
 143
 144         /*!
 145         @brief
 146             \em ERROR level.
 147
 148         Errors that might still allow the execution to continue.
 149
 150         Usually, once one or more errors are reported at this level, the
 151         application, plugin, or library won't perform any more useful
 152         task, but it should still exit cleanly.
 153
 154         The \em ERROR logging statements do not significantly
 155         impact performance.
 156         */
 157         BT_LOGGING_LEVEL_ERROR          = __BT_LOGGING_LEVEL_ERROR,
 158
 159         /*!
 160         @brief
 161             \em FATAL level.
 162
 163         Severe errors that lead the execution to abort immediately.
 164
 165         The \em FATAL logging statements do not significantly
 166         impact performance.
 167         */
 168         BT_LOGGING_LEVEL_FATAL          = __BT_LOGGING_LEVEL_FATAL,
 169
 170         /*!
 171         @brief
 172             Logging is disabled.
 173         */
 174         BT_LOGGING_LEVEL_NONE           = __BT_LOGGING_LEVEL_NONE,
 175 } bt_logging_level;
 176
 177 /*!
 178 @brief
 179     Sets the logging level of all the libbabeltrace2 modules to
 180     \bt_p{logging_level}.
 181
 182 The library's global logging level
 183 \ref api-logging-extra-lib "does not affect" the logging level of
 184 individual components and query operations.
 185
 186 @param[in] logging_level
 187     New library's global logging level.
 188
 189 @sa bt_logging_get_global_level() &mdash;
 190     Returns the current library's global logging level.
 191 */
 192 extern void bt_logging_set_global_level(bt_logging_level logging_level)
 193                 __BT_NOEXCEPT;
 194
 195 /*!
 196 @brief
 197     Returns the current logging level of all the libbabeltrace2 modules.
 198
 199 @returns
 200     Library's current global logging level.
 201
 202 @sa bt_logging_set_global_level() &mdash;
 203     Sets the current library's global logging level.
 204 */
 205 extern bt_logging_level bt_logging_get_global_level(void) __BT_NOEXCEPT;
 206
 207 /*!
 208 @brief
 209     Returns the library's minimal (build-time) logging level.
 210
 211 The library logging statements with a level that's less severe than the
 212 minimal logging level are \em not built.
 213
 214 For example, if the minimal logging level is #BT_LOGGING_LEVEL_INFO, the
 215 #BT_LOGGING_LEVEL_TRACE and #BT_LOGGING_LEVEL_DEBUG logging statements
 216 are not built.
 217
 218 @returns
 219     Library's minimal logging level.
 220
 221 @sa bt_logging_get_global_level() &mdash;
 222     Returns the current library's global logging level.
 223 */
 224 extern bt_logging_level bt_logging_get_minimal_level(void) __BT_NOEXCEPT;
 225
 226 /*! @} */
 227
 228 #ifdef __cplusplus
 229 }
 230 #endif
 231
 232 #endif /* BABELTRACE2_LOGGING_H */