1# HiLog 2 3 4Provides logging functions. 5 6 7For example, you can use logging functions to output logs of the specified log type, service domain, log tag, and log level. 8 9 10@syscap SystemCapability.HiviewDFX.HiLog 11 12 13**Since** 14 15 168 17 18 19## Summary 20 21 22### File 23 24| Name| Description| 25| -------- | -------- | 26| [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| 27 28 29### Macros 30 31| Name| Description| 32| -------- | -------- | 33| [LOG_DOMAIN](#log_domain) 0 | Defines the service domain for a log file.| 34| [LOG_TAG](#log_tag) NULL | Defines a string constant used to identify the class, file, or service.| 35| [OH_LOG_DEBUG](#oh_log_debug)(type, ...) ((void)[OH_LOG_Print](#oh_log_print)((type), LOG_DEBUG, LOG_DOMAIN, LOG_TAG, \_\_VA_ARGS__)) | Outputs DEBUG logs. This is a function-like macro.| 36| [OH_LOG_INFO](#oh_log_info)(type, ...) ((void)[OH_LOG_Print](#oh_log_print)((type), LOG_INFO, LOG_DOMAIN, LOG_TAG, \_\_VA_ARGS__)) | Outputs INFO logs. This is a function-like macro.| 37| [OH_LOG_WARN](#oh_log_warn)(type, ...) ((void)[OH_LOG_Print](#oh_log_print)((type), LOG_WARN, LOG_DOMAIN, LOG_TAG, \_\_VA_ARGS__)) | Outputs WARN logs. This is a function-like macro.| 38| [OH_LOG_ERROR](#oh_log_error)(type, ...) ((void)[OH_LOG_Print](#oh_log_print)((type), LOG_ERROR, LOG_DOMAIN, LOG_TAG, \_\_VA_ARGS__)) | Outputs ERROR logs. This is a function-like macro.| 39| [OH_LOG_FATAL](#oh_log_fatal)(type, ...) ((void)[OH_LOG_Print](#oh_log_print)((type), LOG_FATAL, LOG_DOMAIN, LOG_TAG, \_\_VA_ARGS__)) | Outputs FATAL logs. This is a function-like macro.| 40 41 42### Enum 43 44| Name| Description| 45| -------- | -------- | 46| [LogType](#logtype) { LOG_APP= 0 } | **Log Type**| 47| [LogLevel](#loglevel) { LOG_DEBUG = 3, LOG_INFO = 4, LOG_WARN = 5, LOG_ERROR = 6, LOG_FATAL =7 } | Log level.| 48 49 50### Functions 51 52| Name| Description| 53| -------- | -------- | 54| [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, 5,6))) | Outputs logs.| 55| [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.| 56 57 58## Description 59 60 61## Macro Description 62 63 64### LOG_DOMAIN 65 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** 78 798 80 81 82### LOG_TAG 83 84 85``` 86#define LOG_TAG NULL 87``` 88 89**Description** 90 91Defines a string constant used to identify the class, file, or service. 92 93**Since** 94 958 96 97 98### OH_LOG_DEBUG 99 100 101``` 102#define OH_LOG_DEBUG( type, ... ) ((void)OH_LOG_Print((type), LOG_DEBUG, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 103``` 104 105**Description** 106 107Outputs DEBUG logs. This is a function-like macro. 108 109Before calling this function, define the log service domain and log tag. Generally, you need to define them at the beginning of the source file. 110 111**Parameters** 112 113| Name| Description| 114| -------- | -------- | 115| type | Log type. The type for third-party applications is defined by **LOG_APP**.| 116| 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.| 117| ... | 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.| 118 119**See** 120 121[OH_LOG_Print](#oh_log_print) 122 123**Since** 124 1258 126 127 128### OH_LOG_ERROR 129 130 131``` 132#define OH_LOG_ERROR( type, ... ) ((void)OH_LOG_Print((type), LOG_ERROR, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 133``` 134 135**Description** 136 137Outputs ERROR logs. This is a function-like macro. 138 139Before calling this function, define the log service domain and log tag. Generally, you need to define them at the beginning of the source file. 140 141**Parameters** 142 143| Name| Description| 144| -------- | -------- | 145| type | Log type. The type for third-party applications is defined by **LOG_APP**.| 146| 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.| 147| ... | 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.| 148 149**See** 150 151[OH_LOG_Print](#oh_log_print) 152 153**Since** 154 1558 156 157 158### OH_LOG_FATAL 159 160 161``` 162#define OH_LOG_FATAL( type, ... ) ((void)OH_LOG_Print((type), LOG_FATAL, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 163``` 164 165**Description** 166 167Outputs FATAL logs. This is a function-like macro. 168 169Before calling this function, define the log service domain and log tag. Generally, you need to define them at the beginning of the source file. 170 171**Parameters** 172 173| Name| Description| 174| -------- | -------- | 175| type | Log type. The type for third-party applications is defined by **LOG_APP**.| 176| 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.| 177| ... | 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.| 178 179**See** 180 181[OH_LOG_Print](#oh_log_print) 182 183**Since** 184 1858 186 187 188### OH_LOG_INFO 189 190 191``` 192#define OH_LOG_INFO( type, ... ) ((void)OH_LOG_Print((type), LOG_INFO, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 193``` 194 195**Description** 196 197Outputs INFO logs. This is a function-like macro. 198 199Before calling this function, define the log service domain and log tag. Generally, you need to define them at the beginning of the source file. 200 201**Parameters** 202 203| Name| Description| 204| -------- | -------- | 205| type | Log type. The type for third-party applications is defined by **LOG_APP**.| 206| 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.| 207| ... | 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.| 208 209**See** 210 211[OH_LOG_Print](#oh_log_print) 212 213**Since** 214 2158 216 217 218### OH_LOG_WARN 219 220 221``` 222#define OH_LOG_WARN( type, ... ) ((void)OH_LOG_Print((type), LOG_WARN, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 223``` 224 225**Description** 226 227Outputs WARN logs. This is a function-like macro. 228 229Before calling this function, define the log service domain and log tag. Generally, you need to define them at the beginning of the source file. 230 231**Parameters** 232 233| Name| Description| 234| -------- | -------- | 235| type | Log type. The type for third-party applications is defined by **LOG_APP**.| 236| 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.| 237| ... | 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.| 238 239**See** 240 241[OH_LOG_Print](#oh_log_print) 242 243**Since** 244 2458 246 247 248## Enum Description 249 250 251### LogLevel 252 253 254``` 255enum LogLevel 256``` 257 258**Description** 259 260Enumerates log levels. 261 262You are advised to select log levels based on their respective use cases. 263 264Log levels: 265 266**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. 267 268**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. 269 270**WARN**: indicates a severe, unexpected fault that has little impact on users and can be rectified by the programs themselves or through simple operations. 271 272**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. 273 274**FATAL**: indicates that a program or functionality is about to crash and the fault cannot be rectified. 275 276| Value| Description| 277| -------- | -------- | 278| LOG_DEBUG | DEBUG level to be used by **OH_LOG_DEBUG**.| 279| LOG_INFO | INFO level to be used by **OH_LOG_INFO**.| 280| LOG_WARN | WARN level to be used by **OH_LOG_WARN**.| 281| LOG_ERROR | ERROR level to be used by **OH_LOG_ERROR**.| 282| LOG_FATAL | FATAL level to be used by **OH_LOG_FATAL**.| 283 284**Since** 285 2868 287 288 289### LogType 290 291 292``` 293enum LogType 294``` 295 296**Description** 297 298Enumerates log types. 299 300You can use this function to specify the type of output logs. Currently, only **LOG_APP** is available. 301 302| Value| Description| 303| -------- | -------- | 304| LOG_APP | Application log.| 305 306**Since** 307 3088 309 310 311## Function Description 312 313 314### OH_LOG_IsLoggable() 315 316 317``` 318bool OH_LOG_IsLoggable (unsigned int domain, const char * tag, LogLevel level ) 319``` 320 321**Description** 322 323Checks whether logs of the specified service domain, tag, and level can be printed. 324 325**Parameters** 326 327| Name| Description| 328| -------- | -------- | 329| domain | Service domain.| 330| tag | Log tag.| 331| level | Log level.| 332 333**Returns** 334 335**true** if the specified logs can be output; **false** otherwise. 336 337**Since** 338 3398 340 341 342### OH_LOG_Print() 343 344 345``` 346int OH_LOG_Print (LogType type, LogLevel level, unsigned int domain, const char * tag, const char * fmt, ... ) 347``` 348 349**Description** 350 351Outputs logs. 352 353You 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. 354 355**Parameters** 356 357| Name| Description| 358| -------- | -------- | 359| type | Log type. The type for third-party applications is defined by **LOG_APP**.| 360| level | Log level. The value can be **LOG_DEBUG**, **LOG_INFO**, **LOG_WARN**, **LOG_ERROR**, and **LOG_FATAL**.| 361| domain | Service domain. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFF.| 362| tag | Log tag, which is a string used to identify the class, file, or service.| 363| 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.| 364| ... | 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.| 365 366**Returns** 367 368**0** or a larger value if the operation is successful; a value smaller than **0** otherwise. 369 370**Since** 371 3728 373