1 /* 2 * Copyright (c) 2021-2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef HIVIEWDFX_HILOG_H 17 #define HIVIEWDFX_HILOG_H 18 /** 19 * @addtogroup HiLog 20 * @{ 21 * 22 * @brief Provides logging functions. 23 * 24 * For example, you can use these functions to output logs of the specified log type, service domain, log tag, 25 * and log level. 26 * 27 * @syscap SystemCapability.HiviewDFX.HiLog 28 * 29 * @since 8 30 */ 31 32 /** 33 * @file log.h 34 * 35 * @brief Defines the logging functions of the HiLog module. 36 * 37 * Before outputting logs, you must define the service domain, and log tag, use the function with 38 * the specified log type and level, and specify the privacy identifier.\n 39 * <ul><li>Service domain: used to identify the subsystem and module of a service. Its value is a hexadecimal 40 * integer ranging from 0x0 to 0xFFFF. \n 41 * <li>Log tag: a string used to identify the class, file, or service.</li> \n 42 * <li>Log level: <b>DEBUG</b>, <b>INFO</b>, <b>WARN</b>, <b>ERROR</b>, and <b>FATAL</b></li> \n 43 * <li>Parameter format: a printf format string that starts with a % character, including format specifiers 44 * and variable parameters.</li> \n 45 * <li>Privacy identifier: {public} or {private} added between the % character and the format specifier in 46 * each parameter. Note that each parameter has a privacy identifier. If no privacy identifier is added, 47 * the parameter is considered to be <b>private</b>.</li></ul> \n 48 * 49 * Sample code:\n 50 * Defining the service domain and log tag:\n 51 * #include <hilog/log.h>\n 52 * #define LOG_DOMAIN 0x0201\n 53 * #define LOG_TAG "MY_TAG"\n 54 * Outputting logs:\n 55 * HILOG_WARN({@link LOG_APP}, "Failed to visit %{private}s, reason:%{public}d.", url, errno);\n 56 * Output result:\n 57 * 05-06 15:01:06.870 1051 1051 W 0201/MY_TAG: Failed to visit <private>, reason:503.\n 58 * 59 * @since 8 60 */ 61 62 #ifdef __cplusplus 63 #include <cstdarg> 64 #else 65 #include <stdarg.h> 66 #include <stdbool.h> 67 #endif 68 69 #ifdef __cplusplus 70 extern "C" { 71 #endif 72 73 /** 74 * @brief Defines the service domain for a log file. 75 * 76 * The service domain is used to identify the subsystem and module of a service. Its value is a hexadecimal integer 77 * ranging from 0x0 to 0xFFFF. If the value is beyond the range, its significant bits are automatically truncated. \n 78 * 79 * @since 8 80 */ 81 #ifndef LOG_DOMAIN 82 #define LOG_DOMAIN 0 83 #endif 84 85 /** 86 * @brief Defines a string constant used to identify the class, file, or service. 87 * 88 * @since 8 89 */ 90 #ifndef LOG_TAG 91 #define LOG_TAG NULL 92 #endif 93 94 /** 95 * @brief Enumerates log types. 96 * 97 * Currently, <b>LOG_APP</b> is available. \n 98 * 99 * @since 8 100 */ 101 typedef enum { 102 /** Third-party application logs */ 103 LOG_APP = 0, 104 } LogType; 105 106 /** 107 * @brief Enumerates log levels. 108 * 109 * You are advised to select log levels based on their respective usage scenarios:\n 110 * <ul><li><b>DEBUG</b>: used for debugging and disabled from commercial releases</li> \n 111 * <li><b>INFO</b>: used for logging important system running status and steps in key processes</li> \n 112 * <li><b>WARN</b>: used for logging unexpected exceptions that have little impact on user experience and can 113 * automatically recover. Logs at this level are generally output when such exceptions are detected and 114 * captured.</li> \n 115 * <li><b>ERROR</b>: used for logging malfunction that affects user experience and cannot automatically 116 * recover</li>\n 117 * <li><b>FATAL</b>: used for logging major exceptions that have severely affected user experience and should 118 * not occur.</li></ul> \n 119 * 120 * @since 8 121 */ 122 typedef enum { 123 /** Debug level to be used by {@link OH_LOG_DEBUG} */ 124 LOG_DEBUG = 3, 125 /** Informational level to be used by {@link OH_LOG_INFO} */ 126 LOG_INFO = 4, 127 /** Warning level to be used by {@link OH_LOG_WARN} */ 128 LOG_WARN = 5, 129 /** Error level to be used by {@link OH_LOG_ERROR} */ 130 LOG_ERROR = 6, 131 /** Fatal level to be used by {@link OH_LOG_FATAL} */ 132 LOG_FATAL = 7, 133 } LogLevel; 134 135 /** 136 * @brief Outputs logs. 137 * 138 * You can use this function to output logs based on the specified log type, log level, service domain, log tag, 139 * and variable parameters determined by the format specifier and privacy identifier in the printf format. 140 * 141 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 142 * @param level Indicates the log level, which can be <b>LOG_DEBUG</b>, <b>LOG_INFO</b>, <b>LOG_WARN</b>, 143 * <b>LOG_ERROR</b>, and <b>LOG_FATAL</b>. 144 * @param domain Indicates the service domain of logs. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. 145 * @param tag Indicates the log tag, which is a string used to identify the class, file, or service behavior. 146 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy 147 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier 148 * in each parameter. \n 149 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 150 * in the format string. 151 * @return Returns <b>0</b> or a larger value if the operation is successful; returns a value smaller 152 * than <b>0</b> otherwise. 153 * @since 8 154 */ 155 int OH_LOG_Print(LogType type, LogLevel level, unsigned int domain, const char *tag, const char *fmt, ...) 156 __attribute__((__format__(os_log, 5, 6))); 157 158 /** 159 * @brief Checks whether logs of the specified service domain, log tag, and log level can be output. 160 * 161 * @param domain Indicates the service domain of logs. 162 * @param tag Indicates the log tag. 163 * @param level Indicates the log level. 164 * @return Returns <b>true</b> if the specified logs can be output; returns <b>false</b> otherwise. 165 * @since 8 166 */ 167 bool OH_LOG_IsLoggable(unsigned int domain, const char *tag, LogLevel level); 168 169 /** 170 * @brief Outputs debug logs. This is a function-like macro. 171 * 172 * Before calling this function, define the log service domain and log tag. Generally, you need to define them at 173 * the beginning of the source file. \n 174 * 175 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 176 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the 177 * privacy identifier. Specifically, {public} or {private} is added between the % character and the format specifier 178 * in each parameter. \n 179 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 180 * in the format string. 181 * @see OH_LOG_Print 182 * @since 8 183 */ 184 #define OH_LOG_DEBUG(type, ...) ((void)OH_LOG_Print((type), LOG_DEBUG, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 185 186 /** 187 * @brief Outputs informational logs. This is a function-like macro. 188 * 189 * Before calling this function, define the log service domain and log tag. Generally, you need to define them 190 * at the beginning of the source file. \n 191 * 192 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 193 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy 194 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier in 195 * each parameter. \n 196 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 197 * in the format string. 198 * @see OH_LOG_Print 199 * @since 8 200 */ 201 #define OH_LOG_INFO(type, ...) ((void)OH_LOG_Print((type), LOG_INFO, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 202 203 /** 204 * @brief Outputs warning logs. This is a function-like macro. 205 * 206 * Before calling this function, define the log service domain and log tag. Generally, you need to define them 207 * at the beginning of the source file. \n 208 * 209 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 210 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the 211 * privacy identifier. Specifically, {public} or {private} is added between the % character and the format specifier 212 * in each parameter. \n 213 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 214 * in the format string. 215 * @see OH_LOG_Print 216 * @since 8 217 */ 218 #define OH_LOG_WARN(type, ...) ((void)OH_LOG_Print((type), LOG_WARN, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 219 220 /** 221 * @brief Outputs error logs. This is a function-like macro. 222 * 223 * Before calling this function, define the log service domain and log tag. Generally, you need to define 224 * them at the beginning of the source file. \n 225 * 226 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 227 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy 228 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier in each 229 * parameter. \n 230 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 231 * in the format string. 232 * @see OH_LOG_Print 233 * @since 8 234 */ 235 #define OH_LOG_ERROR(type, ...) ((void)OH_LOG_Print((type), LOG_ERROR, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 236 237 /** 238 * @brief Outputs fatal logs. This is a function-like macro. 239 * 240 * Before calling this function, define the log service domain and log tag. Generally, you need to define them at 241 * the beginning of the source file. \n 242 * 243 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 244 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy 245 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier in 246 * each parameter. \n 247 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 248 * in the format string. 249 * @see OH_LOG_Print 250 * @since 8 251 */ 252 #define OH_LOG_FATAL(type, ...) ((void)OH_LOG_Print((type), LOG_FATAL, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 253 254 /** 255 * @brief Defines the function pointer type for the user-defined log processing function. 256 * 257 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 258 * @param level Indicates the log level, which can be <b>LOG_DEBUG</b>, <b>LOG_INFO</b>, <b>LOG_WARN</b>, 259 * <b>LOG_ERROR</b>, and <b>LOG_FATAL</b>. 260 * @param domain Indicates the service domain of logs. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. 261 * @param tag Indicates the log tag, which is a string used to identify the class, file, or service behavior. 262 * @param msg Indicates the log message itself, which is a formatted log string. 263 * @since 11 264 */ 265 typedef void (*LogCallback)(const LogType type, const LogLevel level, const unsigned int domain, const char *tag, 266 const char *msg); 267 268 /** 269 * @brief Set the user-defined log processing function. 270 * 271 * After calling this function, the callback function implemented by the user can receive all hilogs of the 272 * current process. 273 * Note that it will not change the default behavior of hilog logs of the current process, no matter whether this 274 * interface is called or not. \n 275 * 276 * @param callback Indicates the callback function implemented by the user. If you do not need to process hilog logs, 277 * you can transfer a null pointer. 278 * @since 11 279 */ 280 void OH_LOG_SetCallback(LogCallback callback); 281 282 #ifdef __cplusplus 283 } 284 #endif 285 /** @} */ 286 287 #ifdef HILOG_RAWFORMAT 288 #include "hilog/log_inner.h" 289 #endif 290 291 #endif // HIVIEWDFX_HILOG_C_H 292