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