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 | Defines the service domain for a log file.| 30| [LOG_TAG](#log_tag) NULL | Defines a string constant used to identify the class, file, or service.| 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\_\_)) | Outputs 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\_\_)) | Outputs 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\_\_)) | Outputs 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\_\_)) | Outputs 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\_\_)) | Outputs 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) | Pointer to the callback function. You can customize the processing of logs in the callback.| 43 44 45### Enum 46 47| Name| Description| 48| -------- | -------- | 49| [LogType](#logtype) { LOG_APP = 0 } | **Log Type**| 50| [LogLevel](#loglevel) {<br>LOG_DEBUG = 3,<br>LOG_INFO = 4,<br>LOG_WARN = 5,<br>LOG_ERROR = 6,<br>LOG_FATAL = 7<br>} | Log level.| 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 61 62## Macro Description 63 64 65### LOG_DOMAIN 66 67``` 68#define LOG_DOMAIN 0 69``` 70 71**Description** 72 73Defines the service domain for a log file. 74 75The service domain is used to identify the subsystem and module of a service. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF. If the value is beyond the range, its significant bits are automatically truncated. 76 77**Since**: 8 78 79 80### LOG_TAG 81 82``` 83#define LOG_TAG NULL 84``` 85 86**Description** 87 88Defines a 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. 89 90**Since**: 8 91 92 93### OH_LOG_DEBUG 94 95``` 96#define OH_LOG_DEBUG( type, ... ) ((void)OH_LOG_Print((type), LOG_DEBUG, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 97``` 98 99**Description** 100 101Outputs DEBUG logs. This is a function-like macro. 102 103Before calling this function, define the log service domain and log tag. Generally, you need to define them at the beginning of the source file. 104 105**Since**: 8 106 107**Parameters** 108 109| Name| Description| 110| -------- | -------- | 111| type | Log type. The type for third-party applications is defined by **LOG_APP**.| 112| 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.| 113| ... | 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.| 114 115**See** 116 117[OH_LOG_Print](#oh_log_print) 118 119 120### OH_LOG_ERROR 121 122``` 123#define OH_LOG_ERROR( type, ... ) ((void)OH_LOG_Print((type), LOG_ERROR, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 124``` 125 126**Description** 127 128Outputs ERROR logs. This is a function-like macro. 129 130Before calling this function, define the log service domain and log tag. Generally, you need to define them at the beginning of the source file. 131 132**Since**: 8 133 134**Parameters** 135 136| Name| Description| 137| -------- | -------- | 138| type | Log type. The type for third-party applications is defined by **LOG_APP**.| 139| 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.| 140| ... | 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.| 141 142**See** 143 144[OH_LOG_Print](#oh_log_print) 145 146 147### OH_LOG_FATAL 148 149``` 150#define OH_LOG_FATAL( type, ... ) ((void)HiLogPrint((type), LOG_FATAL, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 151``` 152 153**Description** 154 155Outputs FATAL logs. This is a function-like macro. 156 157Before calling this function, define the log service domain and log tag. Generally, you need to define them at the beginning of the source file. 158 159**Since**: 8 160 161**Parameters** 162 163| Name| Description| 164| -------- | -------- | 165| type | Log type. The type for third-party applications is defined by **LOG_APP**.| 166| 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.| 167| ... | 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.| 168 169**See** 170 171[OH_LOG_Print](#oh_log_print) 172 173 174### OH_LOG_INFO 175 176``` 177#define OH_LOG_INFO( type, ... ) ((void)OH_LOG_Print((type), LOG_INFO, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 178``` 179 180**Description** 181 182Outputs INFO logs. This is a function-like macro. 183 184Before calling this function, define the log service domain and log tag. Generally, you need to define them at the beginning of the source file. 185 186**Since**: 8 187 188**Parameters** 189 190| Name| Description| 191| -------- | -------- | 192| type | Log type. The type for third-party applications is defined by **LOG_APP**.| 193| 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.| 194| ... | 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.| 195 196**See** 197 198[OH_LOG_Print](#oh_log_print) 199 200 201### OH_LOG_WARN 202 203``` 204#define OH_LOG_WARN( type, ... ) ((void)OH_LOG_Print((type), LOG_WARN, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 205``` 206 207**Description** 208 209Outputs WARN logs. This is a function-like macro. 210 211Before calling this function, define the log service domain and log tag. Generally, you need to define them at the beginning of the source file. 212 213**Since**: 8 214 215**Parameters** 216 217| Name| Description| 218| -------- | -------- | 219| type | Log type. The type for third-party applications is defined by **LOG_APP**.| 220| 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.| 221| ... | 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.| 222 223**See** 224 225[OH_LOG_Print](#oh_log_print) 226 227 228## Type Description 229 230 231### LogCallback 232 233``` 234typedef void(* LogCallback) (const LogType type, const LogLevel level, const unsigned int domain, const char *tag, const char *msg) 235``` 236 237**Description** 238 239Pointer to the callback function. You can customize the processing of logs in the callback. 240 241**Since**: 11 242 243**Parameters** 244 245| Name| Description| 246| -------- | -------- | 247| type | Log type. The type for third-party applications is defined by **LOG_APP**.| 248| level | Log level. The value can be **LOG_DEBUG**, **LOG_INFO**, **LOG_WARN**, **LOG_ERROR**, and **LOG_FATAL**.| 249| domain | Service domain. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF.| 250| 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.| 251| msg | Log content, which is made up of formatted log strings.| 252 253 254## Enum Description 255 256 257### LogLevel 258 259``` 260enum LogLevel 261``` 262 263**Description** 264 265Log level. 266 267You are advised to select log levels based on their respective use cases. Log levels: 268 269**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. 270 271**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. 272 273**WARN**: indicates a severe, unexpected fault that has little impact on users and can be rectified by the programs themselves or through simple operations. 274 275**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. 276 277**FATAL**: indicates that a program or functionality is about to crash and the fault cannot be rectified. 278 279**Since**: 8 280 281| Value| Description| 282| -------- | -------- | 283| LOG_DEBUG | DEBUG level to be used by **OH_LOG_DEBUG**.| 284| LOG_INFO | INFO level to be used by **OH_LOG_INFO**.| 285| LOG_WARN | WARN level to be used by **OH_LOG_WARN**.| 286| LOG_ERROR | ERROR level to be used by **OH_LOG_ERROR**.| 287| LOG_FATAL | FATAL level to be used by **OH_LOG_FATAL**.| 288 289 290### LogType 291 292``` 293enum LogType 294``` 295 296**Description** 297 298**Log Type** 299 300You can use this function to specify the type of output logs. Currently, only **LOG_APP** is available. 301 302**Since**: 8 303 304| Value| Description| 305| -------- | -------- | 306| LOG_APP | Application log.| 307 308 309## Function Description 310 311 312### OH_LOG_IsLoggable() 313 314``` 315int bool OH_LOG_IsLoggable (unsigned int domain, const char * tag, LogLevel level ) 316``` 317 318**Description** 319 320Checks whether logs of the specified service domain, tag, and level can be printed. 321 322**Since**: 8 323 324**Parameters** 325 326| Name| Description| 327| -------- | -------- | 328| domain | Service domain.| 329| tag | Log tag.| 330| level | Log level.| 331 332**Returns** 333 334**true** if the specified logs can be output; **false** otherwise. 335 336 337### OH_LOG_Print() 338 339``` 340int OH_LOG_Print (LogType type, LogLevel level, unsigned int domain, const char * tag, const char * fmt, ... ) 341``` 342 343**Description** 344 345Outputs logs. 346 347You can use this function to output logs based on the specified log type, log level, service domain, log tag, and variable parameters determined by the format specifier and privacy identifier in the printf format. 348 349**Since**: 8 350 351**Parameters** 352 353| Name| Description| 354| -------- | -------- | 355| type | Log type. The type for third-party applications is defined by **LOG_APP**.| 356| level | Log level. The value can be **LOG_DEBUG**, **LOG_INFO**, **LOG_WARN**, **LOG_ERROR**, and **LOG_FATAL**.| 357| domain | Service domain. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF.| 358| 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.| 359| 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.| 360| ... | 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.| 361 362**Returns** 363 364**0** or a larger value if the operation is successful; a value smaller than **0** otherwise. 365 366 367### OH_LOG_SetCallback() 368 369``` 370void OH_LOG_SetCallback (LogCallback callback) 371``` 372 373**Description** 374 375Registers a callback function. 376 377After this function is called, the customized callback can take over all logs of the current process. Note that whether this API is called or not, it does not change the default log processing of the current process. 378 379**Since**: 11 380 381**Parameters** 382 383| Name| Description| 384| -------- | -------- | 385| callback | Custom callback function. If processing of logs is not needed, a null pointer can be transferred.| 386