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 /** 17 * @addtogroup HiLog 18 * @{ 19 * 20 * @brief Provides logging functions. 21 * 22 * For example, you can use these functions to output logs of the specified log type, service domain, log tag, 23 * and log level. 24 * 25 * @kit PerformanceAnalysisKit 26 * @syscap SystemCapability.HiviewDFX.HiLog 27 * 28 * @since 8 29 */ 30 31 /** 32 * @file log.h 33 * 34 * @brief Defines the logging functions of the HiLog module. 35 * 36 * Before outputting logs, you must define the service domain, and log tag, use the function with 37 * the specified log type and level, and specify the privacy identifier.\n 38 * <ul><li>Service domain: used to identify the subsystem and module of a service. Its value is a hexadecimal 39 * integer ranging from 0x0 to 0xFFFF. \n 40 * <li>Log tag: a string used to identify the class, file, or service.</li> \n 41 * <li>Log level: <b>DEBUG</b>, <b>INFO</b>, <b>WARN</b>, <b>ERROR</b>, and <b>FATAL</b></li> \n 42 * <li>Parameter format: a printf format string that starts with a % character, including format specifiers 43 * and variable parameters.</li> \n 44 * <li>Privacy identifier: {public} or {private} added between the % character and the format specifier in 45 * each parameter. Note that each parameter has a privacy identifier. If no privacy identifier is added, 46 * the parameter is considered to be <b>private</b>.</li></ul> \n 47 * 48 * Sample code:\n 49 * Defining the service domain and log tag:\n 50 * #include <hilog/log.h>\n 51 * #define LOG_DOMAIN 0x0201\n 52 * #define LOG_TAG "MY_TAG"\n 53 * Outputting logs:\n 54 * HILOG_WARN({@link LOG_APP}, "Failed to visit %{private}s, reason:%{public}d.", url, errno);\n 55 * Output result:\n 56 * 05-06 15:01:06.870 1051 1051 W 0201/MY_TAG: Failed to visit <private>, reason:503.\n 57 * 58 * @library libhilog.so 59 * @syscap SystemCapability.HiviewDFX.HiLog 60 * @since 8 61 */ 62 63 #ifndef HIVIEWDFX_HILOG_H 64 #define HIVIEWDFX_HILOG_H 65 66 #include <stddef.h> 67 #include <stdarg.h> 68 #include <stdbool.h> 69 70 #ifdef __cplusplus 71 extern "C" { 72 #endif 73 74 /** 75 * @brief Defines the service domain for a log file. 76 * 77 * The service domain is used to identify the subsystem and module of a service. Its value is a hexadecimal integer 78 * ranging from 0x0 to 0xFFFF. If the value is beyond the range, its significant bits are automatically truncated. \n 79 * 80 * @since 8 81 */ 82 #ifndef LOG_DOMAIN 83 #define LOG_DOMAIN 0 84 #endif 85 86 /** 87 * @brief Defines a string constant used to identify the class, file, or service. 88 * 89 * @since 8 90 */ 91 #ifndef LOG_TAG 92 #define LOG_TAG NULL 93 #endif 94 95 /** 96 * @brief Enumerates log types. 97 * 98 * Currently, <b>LOG_APP</b> is available. \n 99 * 100 * @since 8 101 */ 102 typedef enum { 103 /** Third-party application logs */ 104 LOG_APP = 0, 105 } LogType; 106 107 /** 108 * @brief Enumerates log levels. 109 * 110 * You are advised to select log levels based on their respective usage scenarios:\n 111 * <ul><li><b>DEBUG</b>: used for debugging and disabled from commercial releases</li> \n 112 * <li><b>INFO</b>: used for logging important system running status and steps in key processes</li> \n 113 * <li><b>WARN</b>: used for logging unexpected exceptions that have little impact on user experience and can 114 * automatically recover. Logs at this level are generally output when such exceptions are detected and 115 * captured.</li> \n 116 * <li><b>ERROR</b>: used for logging malfunction that affects user experience and cannot automatically 117 * recover</li>\n 118 * <li><b>FATAL</b>: used for logging major exceptions that have severely affected user experience and should 119 * not occur.</li></ul> \n 120 * 121 * @since 8 122 */ 123 typedef enum { 124 /** Debug level to be used by {@link OH_LOG_DEBUG} */ 125 LOG_DEBUG = 3, 126 /** Informational level to be used by {@link OH_LOG_INFO} */ 127 LOG_INFO = 4, 128 /** Warning level to be used by {@link OH_LOG_WARN} */ 129 LOG_WARN = 5, 130 /** Error level to be used by {@link OH_LOG_ERROR} */ 131 LOG_ERROR = 6, 132 /** Fatal level to be used by {@link OH_LOG_FATAL} */ 133 LOG_FATAL = 7, 134 } LogLevel; 135 136 /** 137 * @brief Outputs logs. 138 * 139 * You can use this function to output logs based on the specified log type, log level, service domain, log tag, 140 * and variable parameters determined by the format specifier and privacy identifier in the printf format. 141 * 142 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 143 * @param level Indicates the log level, which can be <b>LOG_DEBUG</b>, <b>LOG_INFO</b>, <b>LOG_WARN</b>, 144 * <b>LOG_ERROR</b>, and <b>LOG_FATAL</b>. 145 * @param domain Indicates the service domain of logs. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. 146 * @param tag Indicates the log tag, which is a string used to identify the class, file, or service behavior. 147 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy 148 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier 149 * in each parameter. \n 150 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 151 * in the format string. 152 * @return Returns <b>0</b> or a larger value if the operation is successful; returns a value smaller 153 * than <b>0</b> otherwise. 154 * @since 8 155 */ 156 int OH_LOG_Print(LogType type, LogLevel level, unsigned int domain, const char *tag, const char *fmt, ...) 157 __attribute__((__format__(os_log, 5, 6))); 158 159 /** 160 * @brief Outputs logs. 161 * 162 * You can use this function to output logs based on the specified log type, log level, service domain, log tag, 163 * and message text. 164 * 165 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 166 * @param level Indicates the log level, which can be <b>LOG_DEBUG</b>, <b>LOG_INFO</b>, <b>LOG_WARN</b>, 167 * <b>LOG_ERROR</b>, and <b>LOG_FATAL</b>. 168 * @param domain Indicates the service domain of logs. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. 169 * @param tag Indicates the log tag, which is a string used to identify the class, file, or service behavior. 170 * @param message Indicates the log string. 171 * @return Returns <b>0</b> or a larger value if the operation is successful; returns a value smaller 172 * than <b>0</b> otherwise. 173 * @since 18 174 */ 175 int OH_LOG_PrintMsg(LogType type, LogLevel level, unsigned int domain, const char *tag, const char *message); 176 177 /** 178 * @brief Outputs logs. 179 * 180 * You can use this function to output logs based on the specified log type, log level, service domain, log tag, 181 * message text and message length. 182 * 183 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 184 * @param level Indicates the log level, which can be <b>LOG_DEBUG</b>, <b>LOG_INFO</b>, <b>LOG_WARN</b>, 185 * <b>LOG_ERROR</b>, and <b>LOG_FATAL</b>. 186 * @param domain Indicates the service domain of logs. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. 187 * @param tag Indicates the log tag, which is a string used to identify the class, file, or service behavior. 188 * @param tagLen Indicates the length of tag. 189 * @param message Indicates the log string. 190 * @param messageLen Indicates the length of message. 191 * @return Returns <b>0</b> or a larger value if the operation is successful; returns a value smaller 192 * than <b>0</b> otherwise. 193 * @since 18 194 */ 195 int OH_LOG_PrintMsgByLen(LogType type, LogLevel level, unsigned int domain, const char *tag, size_t tagLen, 196 const char *message, size_t messageLen); 197 198 /** 199 * @brief Outputs logs. 200 * 201 * You can use this function to output logs based on the specified log type, log level, service domain, log tag, 202 * and a va_list instead of variable parameters determined by the format specifier and privacy identifier in the printf 203 * format. 204 * 205 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 206 * @param level Indicates the log level, which can be <b>LOG_DEBUG</b>, <b>LOG_INFO</b>, <b>LOG_WARN</b>, 207 * <b>LOG_ERROR</b>, and <b>LOG_FATAL</b>. 208 * @param domain Indicates the service domain of logs. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. 209 * @param tag Indicates the log tag, which is a string used to identify the class, file, or service behavior. 210 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy 211 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier 212 * in each parameter. \n 213 * @param ap Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 214 * in the format string. 215 * @return Returns <b>0</b> or a larger value if the operation is successful; returns a value smaller 216 * than <b>0</b> otherwise. 217 * @since 18 218 */ 219 int OH_LOG_VPrint(LogType type, LogLevel level, unsigned int domain, const char *tag, const char *fmt, va_list ap) 220 __attribute__((__format__(os_log, 5, 0))); 221 222 /** 223 * @brief Checks whether logs of the specified service domain, log tag, and log level can be output. 224 * 225 * @param domain Indicates the service domain of logs. 226 * @param tag Indicates the log tag. 227 * @param level Indicates the log level. 228 * @return Returns <b>true</b> if the specified logs can be output; returns <b>false</b> otherwise. 229 * @since 8 230 */ 231 bool OH_LOG_IsLoggable(unsigned int domain, const char *tag, LogLevel level); 232 233 /** 234 * @brief Outputs debug logs. This is a function-like macro. 235 * 236 * Before calling this function, define the log service domain and log tag. Generally, you need to define them at 237 * the beginning of the source file. \n 238 * 239 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 240 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the 241 * privacy identifier. Specifically, {public} or {private} is added between the % character and the format specifier 242 * in each parameter. \n 243 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 244 * in the format string. 245 * @see OH_LOG_Print 246 * @since 8 247 */ 248 #define OH_LOG_DEBUG(type, ...) ((void)OH_LOG_Print((type), LOG_DEBUG, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 249 250 /** 251 * @brief Outputs informational logs. This is a function-like macro. 252 * 253 * Before calling this function, define the log service domain and log tag. Generally, you need to define them 254 * at the beginning of the source file. \n 255 * 256 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 257 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy 258 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier in 259 * each parameter. \n 260 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 261 * in the format string. 262 * @see OH_LOG_Print 263 * @since 8 264 */ 265 #define OH_LOG_INFO(type, ...) ((void)OH_LOG_Print((type), LOG_INFO, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 266 267 /** 268 * @brief Outputs warning logs. This is a function-like macro. 269 * 270 * Before calling this function, define the log service domain and log tag. Generally, you need to define them 271 * at the beginning of the source file. \n 272 * 273 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 274 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the 275 * privacy identifier. Specifically, {public} or {private} is added between the % character and the format specifier 276 * in each parameter. \n 277 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 278 * in the format string. 279 * @see OH_LOG_Print 280 * @since 8 281 */ 282 #define OH_LOG_WARN(type, ...) ((void)OH_LOG_Print((type), LOG_WARN, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 283 284 /** 285 * @brief Outputs error logs. This is a function-like macro. 286 * 287 * Before calling this function, define the log service domain and log tag. Generally, you need to define 288 * them at the beginning of the source file. \n 289 * 290 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 291 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy 292 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier in each 293 * parameter. \n 294 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 295 * in the format string. 296 * @see OH_LOG_Print 297 * @since 8 298 */ 299 #define OH_LOG_ERROR(type, ...) ((void)OH_LOG_Print((type), LOG_ERROR, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 300 301 /** 302 * @brief Outputs fatal logs. This is a function-like macro. 303 * 304 * Before calling this function, define the log service domain and log tag. Generally, you need to define them at 305 * the beginning of the source file. \n 306 * 307 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 308 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy 309 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier in 310 * each parameter. \n 311 * @param ... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers 312 * in the format string. 313 * @see OH_LOG_Print 314 * @since 8 315 */ 316 #define OH_LOG_FATAL(type, ...) ((void)OH_LOG_Print((type), LOG_FATAL, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 317 318 /** 319 * @brief Defines the function pointer type for the user-defined log processing function. 320 * 321 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}. 322 * @param level Indicates the log level, which can be <b>LOG_DEBUG</b>, <b>LOG_INFO</b>, <b>LOG_WARN</b>, 323 * <b>LOG_ERROR</b>, and <b>LOG_FATAL</b>. 324 * @param domain Indicates the service domain of logs. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. 325 * @param tag Indicates the log tag, which is a string used to identify the class, file, or service behavior. 326 * @param msg Indicates the log message itself, which is a formatted log string. 327 * @since 11 328 */ 329 typedef void (*LogCallback)(const LogType type, const LogLevel level, const unsigned int domain, const char *tag, 330 const char *msg); 331 332 /** 333 * @brief Set the user-defined log processing function. 334 * 335 * After calling this function, the callback function implemented by the user can receive all hilogs of the 336 * current process. 337 * Note that it will not change the default behavior of hilog logs of the current process, no matter whether this 338 * interface is called or not. \n 339 * 340 * @param callback Indicates the callback function implemented by the user. If you do not need to process hilog logs, 341 * you can transfer a null pointer. 342 * @since 11 343 */ 344 void OH_LOG_SetCallback(LogCallback callback); 345 346 /** 347 * @brief Sets the lowest log level of the current application process. 348 * 349 * @param level log level 350 * @since 15 351 */ 352 void OH_LOG_SetMinLogLevel(LogLevel level); 353 354 #ifdef __cplusplus 355 } 356 #endif 357 /** @} */ 358 359 #ifdef HILOG_RAWFORMAT 360 #include "hilog/log_inner.h" 361 #endif 362 363 #endif // HIVIEWDFX_HILOG_C_H 364