1# HiLog 2 3 4## Overview 5 6Provides logging functions. 7 8For example, you can use logging functions to output logs of the specified log type, service domain, log tag, and log level. 9 10**System capability**: SystemCapability.HiviewDFX.HiLog 11 12**Since**: 8 13 14 15## Summary 16 17 18### File 19 20| Name| Description| 21| -------- | -------- | 22| [log.h](log_8h.md) | Defines the logging functions of the HiLog module.<br>**File to include**��<hilog/log.h> <br>**Library**��libhilog_ndk.z.so | 23 24 25### Macros 26 27| Name| Description| 28| -------- | -------- | 29| [LOG_DOMAIN](#log_domain) 0 | Indicates the service domain for a log file. | 30| [LOG_TAG](#log_tag) NULL | Indicates the string constant used to identify the class, file, or service. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur. | 31| [OH_LOG_DEBUG](#oh_log_debug)(type, ...) ((void) [OH_LOG_Print](#oh_log_print)((type), LOG_DEBUG, [LOG_DOMAIN](#log_domain), [LOG_TAG](#log_tag), \_\_VA_ARGS\_\_)) | Indicates DEBUG logs. This is a function-like macro. | 32| [OH_LOG_INFO](#oh_log_info)(type, ...) ((void) [OH_LOG_Print](#oh_log_print)((type), LOG_INFO, [LOG_DOMAIN](#log_domain), [LOG_TAG](#log_tag), \_\_VA_ARGS\_\_)) | Indicates INFO logs. This is a function-like macro. | 33| [OH_LOG_WARN](#oh_log_warn)(type, ...) ((void) [OH_LOG_Print](#oh_log_print)((type), LOG_WARN, [LOG_DOMAIN](#log_domain), [LOG_TAG](#log_tag), \_\_VA_ARGS\_\_)) | Indicates WARN logs. This is a function-like macro. | 34| [OH_LOG_ERROR](#oh_log_error)(type, ...) ((void) [OH_LOG_Print](#oh_log_print)((type), LOG_ERROR, [LOG_DOMAIN](#log_domain), [LOG_TAG](#log_tag), \_\_VA_ARGS\_\_)) | Indicates ERROR logs. This is a function-like macro. | 35| [OH_LOG_FATAL](#oh_log_fatal)(type, ...) ((void)HiLogPrint((type), LOG_FATAL, [LOG_DOMAIN](#log_domain), [LOG_TAG](#log_tag), \_\_VA_ARGS\_\_)) | Indicates FATAL logs. This is a function-like macro. | 36 37 38### Types 39 40| Name| Description| 41| -------- | -------- | 42| typedef void(\* [LogCallback](#logcallback)) (const [LogType](#logtype) type, const [LogLevel](#loglevel) level, const unsigned int domain, const char \*tag, const char \*msg) | Defines a function for customizing the processing of logs in the callback. | 43 44 45### Enum 46 47| Name| Description| 48| -------- | -------- | 49| [LogType](#logtype) { LOG_APP = 0 } | Enumerates the log types. | 50| [LogLevel](#loglevel) {<br>LOG_DEBUG = 3, LOG_INFO = 4, LOG_WARN = 5, LOG_ERROR = 6,<br>LOG_FATAL = 7<br>} | Enumerates the log levels. | 51 52 53### Functions 54 55| Name| Description| 56| -------- | -------- | 57| int [OH_LOG_Print](#oh_log_print) ([LogType](#logtype) type, [LogLevel](#loglevel) level, unsigned int domain, const char \*tag, const char \*fmt,...) __attribute__((__format__(os_log | Outputs logs. | 58| int bool [OH_LOG_IsLoggable](#oh_log_isloggable) (unsigned int domain, const char \*tag, [LogLevel](#loglevel) level) | Checks whether logs of the specified service domain, tag, and level can be printed. | 59| void [OH_LOG_SetCallback](#oh_log_setcallback) ([LogCallback](#logcallback) callback) | Registers a callback function. | 60| void [OH_LOG_SetMinLogLevel](#oh_log_setminloglevel) ([LogLevel](#loglevel) level) | Sets the minimum log level. When a process prints logs, both the minimum log level and global log level are verified.<br>Therefore, the minimum log level cannot be lower than the global log level. The default [global log level](../../dfx/hilog.md#displaying-and-setting-log-levels) is **Info**.| 61 62 63## Macro Description 64 65 66### LOG_DOMAIN 67 68``` 69#define LOG_DOMAIN 0 70``` 71**Description** 72Indicates the service domain for a log file. 73 74Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. If the value exceeds the range, logs cannot be printed. 75 76**Since**: 8 77 78 79### LOG_TAG 80 81``` 82#define LOG_TAG NULL 83``` 84**Description** 85Indicates the string constant used to identify the class, file, or service. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur. 86 87**Since**: 8 88 89 90### OH_LOG_DEBUG 91 92``` 93#define OH_LOG_DEBUG( type, ... ) ((void)OH_LOG_Print((type), LOG_DEBUG, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 94``` 95**Description** 96Indicates DEBUG logs. This is a function-like macro. 97 98Before calling this function, define the log service domain and log tag. Generally, you need to define them at the beginning of the source file. 99 100**Since**: 8 101 102**Parameters** 103 104| Name| Description| 105| -------- | -------- | 106| type | Log type. The type for third-party applications is defined by **LOG_APP**. | 107| fmt | Format string, which is an enhancement of a printf format string and supports the privacy identifier. Specifically, **{public}** or **{private}** is added between the % character and the format specifier in each parameter. | 108| ... | Parameter list corresponding to the parameter type in the format string. The number and type of parameters must be mapped onto the identifier in the format string. | 109 110**See** 111 112[OH_LOG_Print](#oh_log_print) 113 114 115### OH_LOG_ERROR 116 117``` 118#define OH_LOG_ERROR( type, ... ) ((void)OH_LOG_Print((type), LOG_ERROR, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 119``` 120**Description** 121Indicates ERROR logs. This is a function-like macro. 122 123Before calling this function, define the log service domain and log tag. Generally, you need to define them at the beginning of the source file. 124 125**Since**: 8 126 127**Parameters** 128 129| Name| Description| 130| -------- | -------- | 131| type | Log type. The type for third-party applications is defined by **LOG_APP**. | 132| fmt | Format string, which is an enhancement of a printf format string and supports the privacy identifier. Specifically, **{public}** or **{private}** is added between the % character and the format specifier in each parameter. | 133| ... | Parameter list corresponding to the parameter type in the format string. The number and type of parameters must be mapped onto the identifier in the format string. | 134 135**See** 136 137[OH_LOG_Print](#oh_log_print) 138 139 140### OH_LOG_FATAL 141 142``` 143#define OH_LOG_FATAL( type, ... ) ((void)HiLogPrint((type), LOG_FATAL, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 144``` 145**Description** 146Indicates FATAL logs. This is a function-like macro. 147 148Before calling this function, define the log service domain and log tag. Generally, you need to define them at the beginning of the source file. 149 150**Since**: 8 151 152**Parameters** 153 154| Name| Description| 155| -------- | -------- | 156| type | Log type. The type for third-party applications is defined by **LOG_APP**. | 157| fmt | Format string, which is an enhancement of a printf format string and supports the privacy identifier. Specifically, **{public}** or **{private}** is added between the % character and the format specifier in each parameter. | 158| ... | Parameter list corresponding to the parameter type in the format string. The number and type of parameters must be mapped onto the identifier in the format string. | 159 160**See** 161 162[OH_LOG_Print](#oh_log_print) 163 164 165### OH_LOG_INFO 166 167``` 168#define OH_LOG_INFO( type, ... ) ((void)OH_LOG_Print((type), LOG_INFO, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 169``` 170**Description** 171Outputs INFO logs. This is a function-like macro. 172 173Before calling this function, define the log service domain and log tag. Generally, you need to define them at the beginning of the source file. 174 175**Since**: 8 176 177**Parameters** 178 179| Name| Description| 180| -------- | -------- | 181| type | Log type. The type for third-party applications is defined by **LOG_APP**. | 182| fmt | Format string, which is an enhancement of a printf format string and supports the privacy identifier. Specifically, **{public}** or **{private}** is added between the % character and the format specifier in each parameter. | 183| ... | Parameter list corresponding to the parameter type in the format string. The number and type of parameters must be mapped onto the identifier in the format string. | 184 185**See** 186 187[OH_LOG_Print](#oh_log_print) 188 189 190### OH_LOG_WARN 191 192``` 193#define OH_LOG_WARN( type, ... ) ((void)OH_LOG_Print((type), LOG_WARN, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 194``` 195**Description** 196Indicates WARN logs. This is a function-like macro. 197 198Before calling this function, define the log service domain and log tag. Generally, you need to define them at the beginning of the source file. 199 200**Since**: 8 201 202**Parameters** 203 204| Name| Description| 205| -------- | -------- | 206| type | Log type. The type for third-party applications is defined by **LOG_APP**. | 207| fmt | Format string, which is an enhancement of a printf format string and supports the privacy identifier. Specifically, **{public}** or **{private}** is added between the % character and the format specifier in each parameter. | 208| ... | Parameter list corresponding to the parameter type in the format string. The number and type of parameters must be mapped onto the identifier in the format string. | 209 210**See** 211 212[OH_LOG_Print](#oh_log_print) 213 214 215## Type Description 216 217 218### LogCallback 219 220``` 221typedef void(* LogCallback) (const LogType type, const LogLevel level, const unsigned int domain, const char *tag, const char *msg) 222``` 223**Description** 224Defines a function for customizing the processing of logs in the callback. 225 226**Since**: 11 227 228**Parameters** 229 230| Name| Description| 231| -------- | -------- | 232| type | Log type. The type for third-party applications is defined by **LOG_APP**. | 233| level | Log level. The value can be **LOG_DEBUG**, **LOG_INFO**, **LOG_WARN**, **LOG_ERROR**, and **LOG_FATAL**. | 234| domain | Service domain. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. If the value exceeds the range, logs cannot be printed. | 235| tag | Log tag, which is a string used to identify the class, file, or service. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur. | 236| msg | Log content, which is made up of formatted log strings. | 237 238 239## Enum Description 240 241 242### LogLevel 243 244``` 245enum LogLevel 246``` 247**Description** 248Enumerates the log levels. 249 250You are advised to select log levels based on their respective use cases. Log levels: 251 252**DEBUG**: provides more detailed process information than INFO logs to help developers analyze service processes and locate faults. DEBUG logs are not recorded in official versions by default. They are available in debug versions or in official versions with the debug function enabled. 253 254**INFO**: indicates the key service process nodes and exceptions (for example, no network signal or login failure) that occur during service running. These logs should be recorded by the dominant module in the service to avoid repeated logging conducted by multiple invoked modules or low-level functions. 255 256**WARN**: indicates a severe, unexpected fault that has little impact on users and can be rectified by the programs themselves or through simple operations. 257 258**ERROR**: indicates a program or functional error that affects the normal running or use of the functionality and can be fixed at a high cost, for example, by resetting data. 259 260**FATAL**: indicates that a program or functionality is about to crash and the fault cannot be rectified. 261 262**Since**: 8 263 264| Value| Description| 265| -------- | -------- | 266| LOG_DEBUG | DEBUG level to be used by **OH_LOG_DEBUG**. | 267| LOG_INFO | INFO level to be used by **OH_LOG_INFO**. | 268| LOG_WARN | WARN level to be used by **OH_LOG_WARN**. | 269| LOG_ERROR | ERROR level to be used by **OH_LOG_ERROR**. | 270| LOG_FATAL | FATAL level to be used by **OH_LOG_FATAL**. | 271 272 273### LogType 274 275``` 276enum LogType 277``` 278**Description** 279Enumerates the log types. 280 281You can use this function to specify the type of output logs. Currently, only **LOG_APP** is available. 282 283**Since**: 8 284 285| Value| Description| 286| -------- | -------- | 287| LOG_APP | Application log.| 288 289 290## Function Description 291 292 293### OH_LOG_IsLoggable() 294 295``` 296int bool OH_LOG_IsLoggable (unsigned int domain, const char * tag, LogLevel level ) 297``` 298**Description** 299Checks whether logs of the specified service domain, tag, and level can be printed. 300 301**Since**: 8 302 303**Parameters** 304 305| Name| Description| 306| -------- | -------- | 307| domain | Service domain. | 308| tag | Log tag. | 309| level | Log level. | 310 311**Returns** 312 313**true** if the specified logs can be output; **false** otherwise. 314 315 316### OH_LOG_Print() 317 318``` 319int OH_LOG_Print (LogType type, LogLevel level, unsigned int domain, const char * tag, const char * fmt, ... ) 320``` 321**Description** 322 323 324Outputs logs of the specified **type**, **level**, **domain**, **tag**, and variables determined by the format specifier and privacy identifier in the printf format. 325 326**Since**: 8 327 328**Parameters** 329 330| Name| Description| 331| -------- | -------- | 332| type | Log type. The type for third-party applications is defined by **LOG_APP**. | 333| level | Log level. The value can be **LOG_DEBUG**, **LOG_INFO**, **LOG_WARN**, **LOG_ERROR**, and **LOG_FATAL**. | 334| domain | Service domain. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. If the value exceeds the range, logs cannot be printed. | 335| tag | Log tag, which is a string used to identify the class or service. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur. | 336| fmt | Format string, which is an enhancement of a printf format string and supports the privacy identifier. Specifically, **{public}** or **{private}** is added between the % character and the format specifier in each parameter. | 337| ... | Parameter list corresponding to the parameter type in the format string. The number and type of parameters must be mapped onto the identifier in the format string. | 338 339**Returns** 340 341**0** or a larger value if the operation is successful; a value smaller than **0** otherwise. 342 343 344### OH_LOG_SetCallback() 345 346``` 347void OH_LOG_SetCallback (LogCallback callback) 348``` 349**Description** 350Registers a callback function. 351 352After this function is called, the customized callback can take over all logs of the current process. 353 354Note that whether this API is called or not, it does not change the default log processing of the current process. 355 356**Since**: 11 357 358**Parameters** 359 360| Name| Description| 361| -------- | -------- | 362| callback | Custom callback function. If processing of logs is not needed, a null pointer can be transferred. | 363 364 365### OH_LOG_SetMinLogLevel() 366 367``` 368void OH_LOG_SetMinLogLevel (LogLevel level) 369``` 370**Description** 371Sets the minimum log level. When a process prints logs, both the minimum log level and global log level are verified. 372 373Therefore, the minimum log level cannot be lower than the global log level. The default [global log level](../../dfx/hilog.md#displaying-and-setting-log-levels) is **Info**. 374 375**Since**: 15 376 377**Parameters** 378 379| Name| Description| 380| -------- | -------- | 381| level | Log level. | 382