1# HiLog 2 3 4## 概述 5 6HiLog模块实现日志打印功能。 7 8开发者可以通过使用这些接口实现日志相关功能，输出日志时可以指定日志类型、所属业务领域、日志TAG标识、日志级别等。 9 10**系统能力：** SystemCapability.HiviewDFX.HiLog 11 12**起始版本：** 8 13 14 15## 汇总 16 17 18### 文件 19 20| 名称 | 描述 | 21| -------- | -------- | 22| [log.h](log_8h.md) | HiLog模块日志接口定义，通过这些接口实现日志打印相关功能。<br>**引用文件**：<hilog/log.h> <br>**库**：libhilog_ndk.z.so | 23 24 25### 宏定义 26 27| 名称 | 描述 | 28| -------- | -------- | 29| [LOG_DOMAIN](#log_domain) 0 | 日志所对应的业务领域，用于标识业务的子系统、模块。16进制整数，有效范围为0x0~0xFFFF，超出范围则日志无法打印。 | 30| [LOG_TAG](#log_tag) NULL | 字符串常量，标识调用所在的类或者业务。tag最多为31字节，超出后会截断。不建议使用中文字符，可能出现乱码或者对齐问题。 | 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\_\_)) | DEBUG级别写日志，宏封装接口。 | 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\_\_)) | INFO级别写日志，宏封装接口。 | 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\_\_)) | WARN级别写日志，宏封装接口。 | 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\_\_)) | ERROR级别写日志，宏封装接口。 | 35| [OH_LOG_FATAL](#oh_log_fatal)(type, ...) ((void)HiLogPrint((type), LOG_FATAL, [LOG_DOMAIN](#log_domain), [LOG_TAG](#log_tag), \_\_VA_ARGS\_\_)) | FATAL级别写日志，宏封装接口。 | 36 37 38### 类型定义 39 40| 名称 | 描述 | 41| -------- | -------- | 42| typedef void(\* [LogCallback](#logcallback)) (const [LogType](#logtype) type, const [LogLevel](#loglevel) level, const unsigned int domain, const char \*tag, const char \*msg) | 函数指针，开发者自定义回调函数内容，在回调函数中，可自行对hilog日志进行处理。 | 43 44 45### 枚举 46 47| 名称 | 描述 | 48| -------- | -------- | 49| [LogType](#logtype) { LOG_APP = 0 } | 日志类型。 | 50| [LogLevel](#loglevel) {<br/>LOG_DEBUG = 3,<br>LOG_INFO = 4,<br>LOG_WARN = 5,<br>LOG_ERROR = 6,<br/>LOG_FATAL = 7<br/>} | 日志级别。 | 51 52 53### 函数 54 55| 名称 | 描述 | 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, 5, 6))) | 写日志接口。 | 58| int bool [OH_LOG_IsLoggable](#oh_log_isloggable) (unsigned int domain, const char \*tag, [LogLevel](#loglevel) level) | 检查指定业务领域、TAG、级别的日志是否可以打印。 | 59| void [OH_LOG_SetCallback](#oh_log_setcallback) ([LogCallback](#logcallback) callback) | 注册函数。 | 60| void [OH_LOG_SetMinLogLevel](#oh_log_setminloglevel) ([LogLevel](#loglevel) level) | 设置应用日志打印的最低日志级别。 进程在打印日志时，需要同时校验该日志级别和全局日志级别，<br/>所以设置的日志级别不能低于全局日志级别，[全局日志级别](../../dfx/hilog.md#查看和设置日志级别)默认为Info。 | 61 62 63## 宏定义说明 64 65 66### LOG_DOMAIN 67 68``` 69#define LOG_DOMAIN 0 70``` 71**描述** 72日志所对应的业务领域，用于标识业务的子系统、模块。 73 7416进制整数，有效范围为0x0~0xFFFF，超出范围则日志无法打印。 75 76**起始版本：** 8 77 78 79### LOG_TAG 80 81``` 82#define LOG_TAG NULL 83``` 84**描述** 85字符串常量，标识调用所在的类或者业务。tag最多为31字节，超出后会截断。不建议使用中文字符，可能出现乱码或者对齐问题。 86 87**起始版本：** 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**描述** 96DEBUG级别写日志，宏封装接口。 97 98使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 99 100**起始版本：** 8 101 102**参数:** 103 104| 名称 | 描述 | 105| -------- | -------- | 106| type | 日志类型，三方应用日志类型为LOG_APP。 | 107| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 | 108| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 | 109 110**参见：** 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**描述** 121ERROR级别写日志，宏封装接口。 122 123使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 124 125**起始版本：** 8 126 127**参数:** 128 129| 名称 | 描述 | 130| -------- | -------- | 131| type | 日志类型，三方应用日志类型为LOG_APP。 | 132| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 | 133| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 | 134 135**参见：** 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**描述** 146FATAL级别写日志，宏封装接口。 147 148使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 149 150**起始版本：** 8 151 152**参数:** 153 154| 名称 | 描述 | 155| -------- | -------- | 156| type | 日志类型，三方应用日志类型为LOG_APP。 | 157| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 | 158| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 | 159 160**参见：** 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**描述** 171INFO级别写日志，宏封装接口。 172 173使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 174 175**起始版本：** 8 176 177**参数:** 178 179| 名称 | 描述 | 180| -------- | -------- | 181| type | 日志类型，三方应用日志类型为LOG_APP。 | 182| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 | 183| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 | 184 185**参见：** 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**描述** 196WARN级别写日志，宏封装接口。 197 198使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 199 200**起始版本：** 8 201 202**参数:** 203 204| 名称 | 描述 | 205| -------- | -------- | 206| type | 日志类型，三方应用日志类型为LOG_APP。 | 207| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 | 208| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 | 209 210**参见：** 211 212[OH_LOG_Print](#oh_log_print) 213 214 215## 类型定义说明 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**描述** 224函数指针，开发者自定义回调函数内容，在回调函数中，可自行对hilog日志进行处理。 225 226**起始版本：** 11 227 228**参数:** 229 230| 名称 | 描述 | 231| -------- | -------- | 232| type | 日志类型，三方应用日志类型为LOG_APP。 | 233| level | 日志级别，日志级别包括LOG_DEBUG、LOG_INFO、LOG_WARN、LOG_ERROR、LOG_FATAL。 | 234| domain | 日志业务领域，16进制整数，范围为0x0~0xFFFF，超出范围则日志无法打印。 | 235| tag | 日志TAG，字符串，标识调用所在的类或者业务。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。 | 236| msg | 日志内容，格式化之后的日志字符串。 | 237 238 239## 枚举类型说明 240 241 242### LogLevel 243 244``` 245enum LogLevel 246``` 247**描述** 248日志级别。 249 250该枚举类型用于定义日志级别。各级别建议使用方式： 251 252DEBUG：比INFO级别更详细的流程记录，通过该级别的日志可以更详细地分析业务流程和定位分析问题。DEBUG级别的日志在正式发布版本中默认不会被打印，只有在调试版本或打开调试开关的情况下才会打印。 253 254INFO：用来记录业务关键流程节点，可以还原业务的主要运行过程；用来记录非正常情况信息，但这些情况都是可以预期的(如无网络信号、登录失败等)。这些日志都应该由该业务内处于支配地位的模块来记录，避免在多个被调用的模块或低级函数中重复记录。 255 256WARN：发生了较为严重的非预期情况，但是对用户影响不大，程序可以自动恢复或通过简单的操作就可以恢复的问题。 257 258ERROR：程序或功能发生了错误，该错误会影响功能的正常运行或用户的正常使用，可以恢复但恢复代价较高，如重置数据等。 259 260FATAL：重大致命异常，表明程序或功能即将崩溃，故障无法恢复。 261 262**起始版本：** 8 263 264| 枚举值 | 描述 | 265| -------- | -------- | 266| LOG_DEBUG | DEBUG日志级别，使用OH_LOG_DEBUG接口打印。 | 267| LOG_INFO | INFO日志级别，使用OH_LOG_INFO接口打印。 | 268| LOG_WARN | WARN日志级别，使用OH_LOG_WARN接口打印。 | 269| LOG_ERROR | ERROR日志级别，使用OH_LOG_ERROR接口打印。 | 270| LOG_FATAL | FATAL日志级别，使用OH_LOG_FATAL接口打印。 | 271 272 273### LogType 274 275``` 276enum LogType 277``` 278**描述** 279日志类型。 280 281该枚举类型用于定义应用开发者可以使用的日志类型。当前有应用日志LOG_APP。 282 283**起始版本：** 8 284 285| 枚举值 | 描述 | 286| -------- | -------- | 287| LOG_APP | 应用日志。| 288 289 290## 函数说明 291 292 293### OH_LOG_IsLoggable() 294 295``` 296int bool OH_LOG_IsLoggable (unsigned int domain, const char * tag, LogLevel level ) 297``` 298**描述** 299检查指定业务领域、TAG、级别的日志是否可以打印。 300 301**起始版本：** 8 302 303**参数:** 304 305| 名称 | 描述 | 306| -------- | -------- | 307| domain | 日志业务领域，16进制整数，范围0x0~0xFFFF，超出范围则日志无法打印。 | 308| tag | 日志TAG，字符串，标识调用所在的类或者业务。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。 | 309| level | 日志级别，日志级别包括LOG_DEBUG、LOG_INFO、LOG_WARN、LOG_ERROR、LOG_FATAL。 | 310 311**返回：** 312 313如果指定domain、tag、level日志可以打印则返回true；否则返回false。 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**描述** 322写日志接口。 323 324指定日志类型、日志级别、业务领域、TAG，按照类printf格式类型和隐私指示确定需要输出的变参。 325 326**起始版本：** 8 327 328**参数:** 329 330| 名称 | 描述 | 331| -------- | -------- | 332| type | 日志类型，三方应用日志类型为LOG_APP。 | 333| level | 日志级别，日志级别包括LOG_DEBUG、LOG_INFO、LOG_WARN、LOG_ERROR、LOG_FATAL。 | 334| domain | 日志业务领域，16进制整数，范围0x0~0xFFFF，超出范围则日志无法打印。 | 335| tag | 日志TAG，字符串，标识调用所在的类或者业务。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。 | 336| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 | 337| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 | 338 339**返回：** 340 341大于等于0表示成功；小于0表示失败。 342 343 344### OH_LOG_SetCallback() 345 346``` 347void OH_LOG_SetCallback (LogCallback callback) 348``` 349**描述** 350注册函数。 351 352调用此函数后，用户实现的回调函数可以接收当前进程的所有hilog日志。 353 354请注意，无论是否调用该接口，它都不会更改当前进程的hilog日志的默认行为。 355 356**起始版本：** 11 357 358**参数:** 359 360| 名称 | 描述 | 361| -------- | -------- | 362| callback | 用户实现的回调函数。如果不需要处理hilog日志，可以传输空指针。 | 363 364 365### OH_LOG_SetMinLogLevel() 366 367``` 368void OH_LOG_SetMinLogLevel (LogLevel level) 369``` 370**描述** 371设置应用日志打印的最低日志级别。 进程在打印日志时，需要同时校验该日志级别和全局日志级别， 372 373所以设置的日志级别不能低于全局日志级别，[全局日志级别](../../dfx/hilog.md#查看和设置日志级别)默认为Info。 374 375**起始版本：** 15 376 377**参数:** 378 379| 名称 | 描述 | 380| -------- | -------- | 381| level | 指定日志level。 | 382