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