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