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模块日志接口定义，通过这些接口实现日志打印相关功能。 | 23 24 25### 宏定义 26 27| 名称 | 描述 | 28| -------- | -------- | 29| [LOG_DOMAIN](#log_domain) 0 | 日志所对应的业务领域，用于标识业务的子系统、模块。 | 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级别写日志，宏封装接口。使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 | 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级别写日志，宏封装接口。使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 | 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级别写日志，宏封装接口。使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 | 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级别写日志，宏封装接口。使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 | 35| [OH_LOG_FATAL](#oh_log_fatal)(type, ...) ((void)[OH_LOG_Print](#oh_log_print)((type), LOG_FATAL, [LOG_DOMAIN](#log_domain), [LOG_TAG](#log_tag), \_\_VA_ARGS\_\_)) | FATAL级别写日志，宏封装接口。使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 | 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, LOG_INFO = 4, LOG_WARN = 5, 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 | 写日志接口。指定日志类型、日志级别、业务领域、TAG，按照类printf格式类型和隐私指示确定需要输出的变参。 | 58| int int [OH_LOG_PrintMsg](#oh_log_printmsg) ([LogType](#logtype) type, [LogLevel](#loglevel) level, unsigned int domain, const char \*tag, const char \*message) | 写日志接口。输出指定type、level、domain、tag的常量日志字符串。 | 59| int [OH_LOG_PrintMsgByLen](#oh_log_printmsgbylen) ([LogType](#logtype) type, [LogLevel](#loglevel) level, unsigned int domain, const char \*tag, size_t tagLen, const char \*message, size_t messageLen) | 写日志接口。输出指定domain、tag和日志级别的常量日志字符串，需要指定tag及字符串长度，和OH_LOG_PrintMsg区别是可以接受不带结束符的字符串。 | 60| int [OH_LOG_VPrint](#oh_log_vprint) ([LogType](#logtype) type, [LogLevel](#loglevel) level, unsigned int domain, const char \*tag, const char \*fmt, va_list ap) __attribute__((__format__(os_log | 写日志接口。指定日志类型、日志级别、业务领域、TAG，按照类printf格式类型和隐私指示确定需要输出的变参，变参为va_list类型。 | 61| int bool [OH_LOG_IsLoggable](#oh_log_isloggable) (unsigned int domain, const char \*tag, [LogLevel](#loglevel) level) | 检查指定业务领域、TAG、级别的日志是否可以打印。 | 62| void [OH_LOG_SetCallback](#oh_log_setcallback) ([LogCallback](#logcallback) callback) | 注册函数。 | 63| void [OH_LOG_SetMinLogLevel](#oh_log_setminloglevel) ([LogLevel](#loglevel) level) | 设置应用日志打印的最低日志级别。 进程在打印日志时，需要同时校验该日志级别和全局日志级别，<br/>所以设置的日志级别不能低于全局日志级别，[全局日志级别](../../dfx/hilog.md#查看和设置日志级别)默认为Info。 | 64 65 66## 宏定义说明 67 68 69### LOG_DOMAIN 70 71``` 72#define LOG_DOMAIN 0 73``` 74**描述** 75日志所对应的业务领域，用于标识业务的子系统、模块。 76 7716进制整数，有效范围为0x0~0xFFFF，超出范围则日志无法打印。 78 79**起始版本：** 8 80 81 82### LOG_TAG 83 84``` 85#define LOG_TAG NULL 86``` 87**描述** 88字符串常量，标识调用所在的类或者业务。tag最多为31字节，超出后会截断。不建议使用中文字符，可能出现乱码或者对齐问题。 89 90**起始版本：** 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**描述** 99DEBUG级别写日志，宏封装接口。 100 101使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 102 103**起始版本：** 8 104 105**参数：** 106 107| 名称 | 描述 | 108| -------- | -------- | 109| type | 日志类型，三方应用日志类型为LOG_APP。 | 110| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 | 111| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 | 112 113**参见：** 114 115[OH_LOG_Print](#oh_log_print) 116 117 118### OH_LOG_ERROR 119 120``` 121#define OH_LOG_ERROR( type, ... ) ((void)OH_LOG_Print((type), LOG_ERROR, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 122``` 123**描述** 124ERROR级别写日志，宏封装接口。 125 126使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 127 128**起始版本：** 8 129 130**参数：** 131 132| 名称 | 描述 | 133| -------- | -------- | 134| type | 日志类型，三方应用日志类型为LOG_APP。 | 135| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 | 136| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 | 137 138**参见：** 139 140[OH_LOG_Print](#oh_log_print) 141 142 143### OH_LOG_FATAL 144 145``` 146#define OH_LOG_FATAL( type, ... ) ((void)OH_LOG_Print((type), LOG_FATAL, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 147``` 148**描述** 149FATAL级别写日志，宏封装接口。 150 151使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 152 153**起始版本：** 8 154 155**参数：** 156 157| 名称 | 描述 | 158| -------- | -------- | 159| type | 日志类型，三方应用日志类型为LOG_APP。 | 160| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 | 161| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 | 162 163**参见：** 164 165[OH_LOG_Print](#oh_log_print) 166 167 168### OH_LOG_INFO 169 170``` 171#define OH_LOG_INFO( type, ... ) ((void)OH_LOG_Print((type), LOG_INFO, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 172``` 173**描述** 174INFO级别写日志，宏封装接口。 175 176使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 177 178**起始版本：** 8 179 180**参数：** 181 182| 名称 | 描述 | 183| -------- | -------- | 184| type | 日志类型，三方应用日志类型为LOG_APP。 | 185| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 | 186| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 | 187 188**参见：** 189 190[OH_LOG_Print](#oh_log_print) 191 192 193### OH_LOG_WARN 194 195``` 196#define OH_LOG_WARN( type, ... ) ((void)OH_LOG_Print((type), LOG_WARN, LOG_DOMAIN, LOG_TAG, __VA_ARGS__)) 197``` 198**描述** 199WARN级别写日志，宏封装接口。 200 201使用时需要先定义日志业务领域、日志TAG，一般在源文件起始处统一定义一次。 202 203**起始版本：** 8 204 205**参数：** 206 207| 名称 | 描述 | 208| -------- | -------- | 209| type | 日志类型，三方应用日志类型为LOG_APP。 | 210| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 | 211| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 | 212 213**参见：** 214 215[OH_LOG_Print](#oh_log_print) 216 217 218## 类型定义说明 219 220 221### LogCallback 222 223``` 224typedef void(* LogCallback) (const LogType type, const LogLevel level, const unsigned int domain, const char *tag, const char *msg) 225``` 226**描述** 227函数指针，开发者自定义回调函数内容，在回调函数中，可自行对hilog日志进行处理。 228 229**起始版本：** 11 230 231**参数：** 232 233| 名称 | 描述 | 234| -------- | -------- | 235| type | 日志类型，三方应用日志类型为LOG_APP。 | 236| level | 日志级别，日志级别包括LOG_DEBUG、LOG_INFO、LOG_WARN、LOG_ERROR、LOG_FATAL。 | 237| domain | 日志业务领域，16进制整数，范围为0x0~0xFFFF，超出范围则日志无法打印。 | 238| tag | 日志TAG，字符串，标识调用所在的类或者业务。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。 | 239| msg | 日志内容，格式化之后的日志字符串。 | 240 241 242## 枚举类型说明 243 244 245### LogLevel 246 247``` 248enum LogLevel 249``` 250**描述** 251日志级别。 252 253该枚举类型用于定义日志级别。各级别建议使用方式： 254 255DEBUG：比INFO级别更详细的流程记录，通过该级别的日志可以更详细地分析业务流程和定位分析问题。DEBUG级别的日志在正式发布版本中默认不会被打印，只有在调试版本或打开调试开关的情况下才会打印。 256 257INFO：用来记录业务关键流程节点，可以还原业务的主要运行过程；用来记录非正常情况信息，但这些情况都是可以预期的(如无网络信号、登录失败等)。这些日志都应该由该业务内处于支配地位的模块来记录，避免在多个被调用的模块或低级函数中重复记录。 258 259WARN：发生了较为严重的非预期情况，但是对用户影响不大，程序可以自动恢复或通过简单的操作就可以恢复的问题。 260 261ERROR：程序或功能发生了错误，该错误会影响功能的正常运行或用户的正常使用，可以恢复但恢复代价较高，如重置数据等。 262 263FATAL：重大致命异常，表明程序或功能即将崩溃，故障无法恢复。 264 265**起始版本：** 8 266 267| 枚举值 | 描述 | 268| -------- | -------- | 269| LOG_DEBUG | DEBUG日志级别，使用OH_LOG_DEBUG接口打印。 | 270| LOG_INFO | INFO日志级别，使用OH_LOG_INFO接口打印。 | 271| LOG_WARN | WARN日志级别，使用OH_LOG_WARN接口打印。 | 272| LOG_ERROR | ERROR日志级别，使用OH_LOG_ERROR接口打印。 | 273| LOG_FATAL | FATAL日志级别，使用OH_LOG_FATAL接口打印。 | 274 275 276### LogType 277 278``` 279enum LogType 280``` 281**描述** 282日志类型。 283 284该枚举类型用于定义应用开发者可以使用的日志类型。当前有应用日志LOG_APP。 285 286**起始版本：** 8 287 288| 枚举值 | 描述 | 289| -------- | -------- | 290| LOG_APP | 应用日志。| 291 292 293## 函数说明 294 295 296### OH_LOG_IsLoggable() 297 298``` 299int bool OH_LOG_IsLoggable (unsigned int domain, const char * tag, LogLevel level ) 300``` 301**描述** 302检查指定业务领域、TAG、级别的日志是否可以打印。 303 304**起始版本：** 8 305 306**参数：** 307 308| 名称 | 描述 | 309| -------- | -------- | 310| domain | 日志业务领域，16进制整数，范围0x0~0xFFFF，超出范围则日志无法打印。 | 311| tag | 日志TAG，字符串，标识调用所在的类或者业务。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。 | 312| level | 日志级别，日志级别包括LOG_DEBUG、LOG_INFO、LOG_WARN、LOG_ERROR、LOG_FATAL。 | 313 314**返回：** 315 316如果指定domain、tag、level日志可以打印则返回true；否则返回false。 317 318 319### OH_LOG_Print() 320 321``` 322int OH_LOG_Print (LogType type, LogLevel level, unsigned int domain, const char * tag, const char * fmt, ... ) 323``` 324**描述** 325写日志接口。 326 327指定日志类型、日志级别、业务领域、TAG，按照类printf格式类型和隐私指示确定需要输出的变参。 328 329**起始版本：** 8 330 331**参数：** 332 333| 名称 | 描述 | 334| -------- | -------- | 335| type | 日志类型，三方应用日志类型为LOG_APP。 | 336| level | 日志级别，日志级别包括LOG_DEBUG、LOG_INFO、LOG_WARN、LOG_ERROR、LOG_FATAL。 | 337| domain | 日志业务领域，16进制整数，范围0x0~0xFFFF，超出范围则日志无法打印。 | 338| tag | 日志TAG，字符串，标识调用所在的类或者业务。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。 | 339| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中%符号后类型前增加{public}、{private}标识。 | 340| ... | 与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 | 341 342**返回：** 343 344大于等于0表示成功；小于0表示失败。 345失败原因：LogLevel传入的级别低于当前允许打印的级别、domain超出范围、tag为空指针、以及CPU高负载、低内存、整机日志量过大等场景下日志写入socket失败。 346 347 348### OH_LOG_PrintMsg() 349 350``` 351int OH_LOG_PrintMsg (LogType type, LogLevel level, unsigned int domain, const char * tag, const char * message ) 352``` 353**描述** 354写日志接口。输出指定type、level、domain、tag的常量日志字符串。 355 356**起始版本：** 18 357 358**参数：** 359 360| 名称 | 描述 | 361| -------- | -------- | 362| type | 日志类型，三方应用日志类型为LOG_APP。 | 363| level | 日志级别，日志级别包括LOG_DEBUG、LOG_INFO、LOG_WARN、LOG_ERROR、LOG_FATAL。 | 364| domain | 日志业务领域，16进制整数，范围为0x0~0xFFFF，超出范围则日志无法打印。 | 365| tag | 日志TAG，字符串，标识调用所在的类或者业务。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。 | 366| message | 常量日志字符串。 | 367 368**返回：** 369 370大于等于0表示成功；小于0表示失败。 371失败原因：LogLevel传入的级别低于当前允许打印的级别、domain超出范围、tag为空指针、以及CPU高负载、低内存、整机日志量过大等场景下日志写入socket失败。 372 373 374### OH_LOG_PrintMsgByLen() 375 376``` 377int OH_LOG_PrintMsgByLen (LogType type, LogLevel level, unsigned int domain, const char * tag, size_t tagLen, const char * message, size_t messageLen ) 378``` 379**描述** 380写日志接口。输出指定domain、tag和日志级别的常量日志字符串，需要指定tag及字符串长度，和OH_LOG_PrintMsg区别是可以接受不带结束符的字符串。 381 382**起始版本：** 18 383 384**参数：** 385 386| 名称 | 描述 | 387| -------- | -------- | 388| type | 日志类型，三方应用日志类型为LOG_APP。 | 389| level | 日志级别，日志级别包括LOG_DEBUG、LOG_INFO、LOG_WARN、LOG_ERROR、LOG_FATAL。 | 390| domain | 日志业务领域，16进制整数，范围为0x0~0xFFFF，超出范围则日志无法打印。 | 391| tag | 日志TAG，字符串，标识调用所在的类或者业务。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。 | 392| tagLen | tag长度。 | 393| message | 常量日志字符串。 | 394| messageLen | 常量字符串长度，小于3500。 | 395 396**返回：** 397 398大于等于0表示成功；小于0表示失败。 399失败原因：LogLevel传入的级别低于当前允许打印的级别、domain超出范围、tag为空指针、以及CPU高负载、低内存、整机日志量过大等场景下日志写入socket失败。 400 401### OH_LOG_VPrint() 402 403``` 404int OH_LOG_VPrint(LogType type, LogLevel level, unsigned int domain, const char *tag, const char *fmt, va_list ap) 405``` 406 407**描述** 408 409写日志接口。指定日志类型、日志级别、业务领域、TAG，按照类printf格式类型和隐私指示确定需要输出的变参，变参为va_list类型。 410 411**起始版本：** 18 412 413**参数：** 414 415| 名称 | 描述 | 416| -------- | -------- | 417| type | 日志类型，三方应用日志类型为LOG_APP。 | 418| level | 日志级别，日志级别包括LOG_DEBUG、LOG_INFO、LOG_WARN、LOG_ERROR、LOG_FATAL。 | 419| domain | 日志业务领域，16进制整数，范围为0x0~0xFFFF，超出范围则日志无法打印。 | 420| tag | 日志TAG，字符串，标识调用所在的类或者业务。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。 | 421| fmt | 格式化字符串，基于类printf格式的增强，支持隐私参数标识，即在格式字符串每个参数中符号后类型前增加{public}、{private}标识。 | 422| ap | va_list类型，与格式字符串里参数类型对应的参数列表，参数数目、参数类型必须与格式字符串中的标识一一对应。 | 423 424**返回：** 425 426大于等于0表示成功；小于0表示失败。 427失败原因：LogLevel传入的级别低于当前允许打印的级别、domain超出范围、tag为空指针、以及CPU高负载、低内存、整机日志量过大等场景下日志写入socket失败。 428 429### OH_LOG_SetCallback() 430 431``` 432void OH_LOG_SetCallback (LogCallback callback) 433``` 434**描述** 435注册函数。 436 437调用此函数后，用户实现的回调函数可以接收当前进程的所有hilog日志。 438 439请注意，无论是否调用该接口，它都不会更改当前进程的hilog日志的默认行为。 440 441**起始版本：** 11 442 443**参数：** 444 445| 名称 | 描述 | 446| -------- | -------- | 447| callback | 用户实现的回调函数。如果不需要处理hilog日志，可以传输空指针。 | 448 449 450### OH_LOG_SetMinLogLevel() 451 452``` 453void OH_LOG_SetMinLogLevel (LogLevel level) 454``` 455**描述** 456设置应用日志打印的最低日志级别。 进程在打印日志时，需要同时校验该日志级别和全局日志级别， 457 458所以设置的日志级别不能低于全局日志级别，[全局日志级别](../../dfx/hilog.md#查看和设置日志级别)默认为Info。 459 460**起始版本：** 15 461 462**参数：** 463 464| 名称 | 描述 | 465| -------- | -------- | 466| level | 指定日志level。 | 467