| 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() — |
| 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() — |
| 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() — |
| 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 */ |