include/babeltrace2/logging.h

   1 #ifndef BABELTRACE2_LOGGING_H
   2 #define BABELTRACE2_LOGGING_H
   3
   4 /*
   5  * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
   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
  26 #ifndef __BT_IN_BABELTRACE_H
  27 # error "Please include <babeltrace2/babeltrace.h> instead."
  28 #endif
  29
  30 #include <babeltrace2/logging-defs.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /*!
  37 @defgroup api-logging Logging
  38
  39 @brief
  40     Logging level enumerators and library logging control.
  41
  42 The logging API offers logging level enumerators (#bt_logging_level)
  43 as 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
  50 libbabeltrace2 contains many hundreds of logging statements to help you
  51 follow and debug your plugin or program.
  52
  53 The library's initial logging level is controlled by the
  54 \c LIBBABELTRACE2_INIT_LOG_LEVEL environment variable. If this
  55 environment variable is not set at library load time, the library's
  56 initial logging level is #BT_LOGGING_LEVEL_NONE. See
  57 \ref api-fund-logging to learn more.
  58
  59 Set libbabeltrace2's current logging level with
  60 bt_logging_set_global_level().
  61
  62 \anchor api-logging-extra-lib bt_logging_set_global_level() only
  63 controls <strong>libbabeltrace2</strong>'s logging level; it does \em
  64 not 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.
  73
  74 - A \ref api-qexec "query operation":
  75   bt_query_executor_set_logging_level() controls this.
  76
  77 - The bt_get_greatest_operative_mip_version() operation: its
  78   \bt_p{logging_level} parameter controls this.
  79
  80 As of \bt_name_version_min_maj, there's no module-specific logging level
  81 control: bt_logging_set_global_level() sets the logging level of all the
  82 library's modules.
  83
  84 libbabeltrace2 writes its logging statements to the standard error
  85 stream. A logging line looks like this:
  86
  87 @code{.unparsed}
  88 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
  89 @endcode
  90
  91 See \ref api-fund-logging to learn more about the logging statement
  92 line's format.
  93
  94 You can set a \em minimal logging level at the \bt_name project's build
  95 time (see \ref api-fund-logging to learn how). The logging statements
  96 with a level that's less severe than the minimal logging level are \em
  97 not 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
 100 bt_logging_get_minimal_level() to get the library's minimal logging
 101 level.
 102 */
 103
 104 /*! @{ */
 105
 106 /*!
 107 @brief
 108     Logging level enumerators.
 109 */
 110 typedef enum bt_logging_level {
 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         */
 120         BT_LOGGING_LEVEL_TRACE          = __BT_LOGGING_LEVEL_TRACE,
 121
 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.
 131         */
 132         BT_LOGGING_LEVEL_DEBUG          = __BT_LOGGING_LEVEL_DEBUG,
 133
 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.
 143         */
 144         BT_LOGGING_LEVEL_INFO           = __BT_LOGGING_LEVEL_INFO,
 145
 146         /*!
 147         @brief
 148             \em WARNING level.
 149
 150         Unexpected situations which still allow the execution to
 151         continue.
 152
 153         The \em WARNING logging statements do not significantly
 154         impact performance.
 155         */
 156         BT_LOGGING_LEVEL_WARNING        = __BT_LOGGING_LEVEL_WARNING,
 157
 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.
 170         */
 171         BT_LOGGING_LEVEL_ERROR          = __BT_LOGGING_LEVEL_ERROR,
 172
 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.
 181         */
 182         BT_LOGGING_LEVEL_FATAL          = __BT_LOGGING_LEVEL_FATAL,
 183
 184         /*!
 185         @brief
 186             Logging is disabled.
 187         */
 188         BT_LOGGING_LEVEL_NONE           = __BT_LOGGING_LEVEL_NONE,
 189 } bt_logging_level;
 190
 191 /*!
 192 @brief
 193     Sets the logging level of all the libbabeltrace2 modules to
 194     \bt_p{logging_level}.
 195
 196 The library's global logging level
 197 \ref api-logging-extra-lib "does not affect" the logging level of
 198 individual components and query operations.
 199
 200 @param[in] logging_level
 201     New library's global logging level.
 202
 203 @sa bt_logging_get_global_level() &mdash;
 204     Returns the current library's global logging level.
 205 */
 206 extern void bt_logging_set_global_level(bt_logging_level logging_level);
 207
 208 /*!
 209 @brief
 210     Returns the current logging level of all the libbabeltrace2 modules.
 211
 212 @returns
 213     Library's current global logging level.
 214
 215 @sa bt_logging_set_global_level() &mdash;
 216     Sets the current library's global logging level.
 217 */
 218 extern bt_logging_level bt_logging_get_global_level(void);
 219
 220 /*!
 221 @brief
 222     Returns the library's minimal (build-time) logging level.
 223
 224 The library logging statements with a level that's less severe than the
 225 minimal logging level are \em not built.
 226
 227 For example, if the minimal logging level is #BT_LOGGING_LEVEL_INFO, the
 228 #BT_LOGGING_LEVEL_TRACE and #BT_LOGGING_LEVEL_DEBUG logging statements
 229 are not built.
 230
 231 @returns
 232     Library's minimal logging level.
 233
 234 @sa bt_logging_get_global_level() &mdash;
 235     Returns the current library's global logging level.
 236 */
 237 extern bt_logging_level bt_logging_get_minimal_level(void);
 238
 239 /*! @} */
 240
 241 #ifdef __cplusplus
 242 }
 243 #endif
 244
 245 #endif /* BABELTRACE2_LOGGING_H */