1# @ohos.hilog (HiLog日志打印) 2 3<!--Kit: Performance Analysis Kit--> 4<!--Subsystem: HiviewDFX--> 5<!--Owner: @liuyifeifei;@buzhenwang--> 6<!--Designer: @shenchenkai--> 7<!--Tester: @liyang2235--> 8<!--Adviser: @foryourself--> 9 10hilog日志系统，使应用/服务可以按照指定级别、标识和格式字符串输出日志内容，帮助开发者了解应用/服务的运行状态，更好地调试程序。 11 12> **说明：** 13> 14> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15 16## 导入模块 17 18```js 19import { hilog } from '@kit.PerformanceAnalysisKit'; 20``` 21 22## hilog.isLoggable 23 24isLoggable(domain: number, tag: string, level: LogLevel) : boolean 25 26在打印日志前调用该接口，用于检查指定领域标识、日志标识和级别的日志是否可以打印。 27 28**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 29 30**系统能力**：SystemCapability.HiviewDFX.HiLog 31 32**参数：** 33 34| 参数名 | 类型 | 必填 | 说明 | 35| ------ | --------------------- | ---- | ------------------------------------------------------------ | 36| domain | number | 是 | 日志对应的领域标识，范围是0x0~0xFFFF，超出范围则日志无法打印。<br/>建议开发者在应用内根据需要自定义划分。 | 37| tag | string | 是 | 指定日志标识，可以为任意字符串，建议用于标识调用所在的类或者业务行为。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。 | 38| level | [LogLevel](#loglevel) | 是 | 日志级别。 | 39 40**返回值：** 41 42| 类型 | 说明 | 43| ------- | ------------------------------------------------------------ | 44| boolean | 如果返回true，则该领域标识、日志标识和级别的日志可以打印，否则不能打印。 | 45 46**示例：** 47 48```js 49hilog.isLoggable(0x0001, "testTag", hilog.LogLevel.INFO); 50``` 51 52## LogLevel 53 54日志级别。 55 56**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 57 58**系统能力**：SystemCapability.HiviewDFX.HiLog 59 60| 名称 | 值 | 说明 | 61| ----- | ------ | ------------------------------------------------------------ | 62| DEBUG | 3 | 详细的流程记录，通过该级别的日志可以更详细地分析业务流程和定位分析问题。 | 63| INFO | 4 | 用于记录业务关键流程节点，可以还原业务的主要运行过程；<br/>用于记录可预料的非正常情况信息，如无网络信号、登录失败等。<br/>这些日志都应该由该业务内处于支配地位的模块来记录，避免在多个被调用的模块或低级函数中重复记录。 | 64| WARN | 5 | 用于记录较为严重的非预期情况，但是对用户影响不大，应用可以自动恢复或通过简单的操作就可以恢复的问题。 | 65| ERROR | 6 | 应用发生了错误，该错误会影响功能的正常运行或用户的正常使用，可以恢复但恢复代价较高，如重置数据等。 | 66| FATAL | 7 | 重大致命异常，表明应用即将崩溃，故障无法恢复。 | 67 68## hilog.debug 69 70debug(domain: number, tag: string, format: string, ...args: any[]) : void 71 72打印DEBUG级别的日志。 73 74DEBUG级别的日志在正式发布版本中默认不被打印，只有在调试版本或打开调试开关的情况下才会打印。 75 76**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 77 78**系统能力**：SystemCapability.HiviewDFX.HiLog 79 80**参数：** 81 82| 参数名 | 类型 | 必填 | 说明 | 83| ------ | ------ | ---- | ------------------------------------------------------------ | 84| domain | number | 是 | 日志对应的领域标识，范围是0x0~0xFFFF，超出范围则日志无法打印。<br/>建议开发者在应用内根据需要自定义划分。 | 85| tag | string | 是 | 指定日志标识，可以为任意字符串，建议用于标识调用所在的类或者业务行为。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。 | 86| format | string | 是 | 格式字符串，用于日志的格式化输出。格式字符串中可以设置多个参数，参数需要包含参数类型、隐私标识。<br>隐私标识分为{public}和{private}，缺省为{private}。标识{public}的内容明文输出，标识{private}的内容以\<private>过滤回显。 | 87| args | any[] | 否 | 与格式字符串format对应的可变长度参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 | 88 89**示例：** 90 91输出一条DEBUG信息，格式字符串为`"%{public}s World %{private}d"`。其中变参`%{public}s`为明文显示的字符串；`%{private}d`为隐私的整型数。 92 93```js 94hilog.debug(0x0001, "testTag", "%{public}s World %{private}d", "hello", 3); 95``` 96 97字符串`"hello"`填入`%{public}s`，整型数`3`填入`%{private}d`，输出日志： 98 99``` 10008-05 12:21:47.579 2695 2703 D A00001/testTag: hello World <private> 101``` 102 103## hilog.info 104 105info(domain: number, tag: string, format: string, ...args: any[]) : void 106 107打印INFO级别的日志。 108 109**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 110 111**系统能力**：SystemCapability.HiviewDFX.HiLog 112 113**参数：** 114 115| 参数名 | 类型 | 必填 | 说明 | 116| ------ | ------ | ---- | ------------------------------------------------------------ | 117| domain | number | 是 | 日志对应的领域标识，范围是0x0~0xFFFF，超出范围则日志无法打印。<br/>建议开发者在应用内根据需要自定义划分。 | 118| tag | string | 是 | 指定日志标识，可以为任意字符串，建议用于标识调用所在的类或者业务行为。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。 | 119| format | string | 是 | 格式字符串，用于日志的格式化输出。格式字符串中可以设置多个参数，参数需要包含参数类型、隐私标识。<br/>隐私标识分为{public}和{private}，缺省为{private}。标识{public}的内容明文输出，标识{private}的内容以\<private>过滤回显。 | 120| args | any[] | 否 | 与格式字符串format对应的可变长度参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 | 121 122**示例：** 123 124输出一条INFO信息，格式字符串为`"%{public}s World %{private}d"`。其中变参`%{public}s`为明文显示的字符串；`%{private}d`为隐私的整型数。 125 126```js 127hilog.info(0x0001, "testTag", "%{public}s World %{private}d", "hello", 3); 128``` 129 130字符串`"hello"`填入`%{public}s`，整型数`3`填入`%{private}d`，输出日志： 131 132``` 13308-05 12:21:47.579 2695 2703 I A00001/testTag: hello World <private> 134``` 135 136## hilog.warn 137 138warn(domain: number, tag: string, format: string, ...args: any[]) : void 139 140打印WARN级别的日志。 141 142**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 143 144**系统能力**：SystemCapability.HiviewDFX.HiLog 145 146**参数：** 147 148| 参数名 | 类型 | 必填 | 说明 | 149| ------ | ------ | ---- | ------------------------------------------------------------ | 150| domain | number | 是 | 日志对应的领域标识，范围是0x0~0xFFFF，超出范围则日志无法打印。<br/>建议开发者在应用内根据需要自定义划分。 | 151| tag | string | 是 | 指定日志标识，可以为任意字符串，建议用于标识调用所在的类或者业务行为。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。 | 152| format | string | 是 | 格式字符串，用于日志的格式化输出。格式字符串中可以设置多个参数，参数需要包含参数类型、隐私标识。<br/>隐私标识分为{public}和{private}，缺省为{private}。标识{public}的内容明文输出，标识{private}的内容以\<private>过滤回显。 | 153| args | any[] | 否 | 与格式字符串format对应的可变长度参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 | 154 155**示例：** 156 157输出一条WARN信息，格式字符串为`"%{public}s World %{private}d"`。其中变参`%{public}s`为明文显示的字符串；`%{private}d`为隐私的整型数。 158 159```js 160hilog.warn(0x0001, "testTag", "%{public}s World %{private}d", "hello", 3); 161``` 162 163字符串`"hello"`填入`%{public}s`，整型数`3`填入`%{private}d`，输出日志： 164 165``` 16608-05 12:21:47.579 2695 2703 W A00001/testTag: hello World <private> 167``` 168 169## hilog.error 170 171error(domain: number, tag: string, format: string, ...args: any[]) : void 172 173打印ERROR级别的日志。 174 175**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 176 177**系统能力**：SystemCapability.HiviewDFX.HiLog 178 179**参数：** 180 181| 参数名 | 类型 | 必填 | 说明 | 182| ------ | ------ | ---- | ------------------------------------------------------------ | 183| domain | number | 是 | 日志对应的领域标识，范围是0x0~0xFFFF，超出范围则日志无法打印。<br/>建议开发者在应用内根据需要自定义划分。 | 184| tag | string | 是 | 指定日志标识，可以为任意字符串，建议用于标识调用所在的类或者业务行为。 tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。| 185| format | string | 是 | 格式字符串，用于日志的格式化输出。格式字符串中可以设置多个参数，参数需要包含参数类型、隐私标识。<br/>隐私标识分为{public}和{private}，缺省为{private}。标识{public}的内容明文输出，标识{private}的内容以\<private>过滤回显。 | 186| args | any[] | 否 | 与格式字符串format对应的可变长度参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 | 187 188**示例：** 189 190输出一条ERROR信息，格式字符串为`"%{public}s World %{private}d"`。其中变参`%{public}s`为明文显示的字符串；`%{private}d`为隐私的整型数。 191 192```js 193hilog.error(0x0001, "testTag", "%{public}s World %{private}d", "hello", 3); 194``` 195 196字符串`"hello"`填入`%{public}s`，整型数`3`填入`%{private}d`，输出日志： 197 198``` 19908-05 12:21:47.579 2695 2703 E A00001/testTag: hello World <private> 200``` 201 202## hilog.fatal 203 204fatal(domain: number, tag: string, format: string, ...args: any[]) : void 205 206打印FATAL级别的日志。 207 208**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 209 210**系统能力**：SystemCapability.HiviewDFX.HiLog 211 212**参数：** 213 214| 参数名 | 类型 | 必填 | 说明 | 215| ------ | ------ | ---- | ------------------------------------------------------------ | 216| domain | number | 是 | 日志对应的领域标识，范围是0x0~0xFFFF，超出范围则日志无法打印。<br/>建议开发者在应用内根据需要自定义划分。 | 217| tag | string | 是 | 指定日志标识，可以为任意字符串，建议用于标识调用所在的类或者业务行为。tag最多为31字节，超出后会截断，不建议使用中文字符，可能出现乱码或者对齐问题。 | 218| format | string | 是 | 格式字符串，用于日志的格式化输出。格式字符串中可以设置多个参数，参数需要包含参数类型、隐私标识。<br/>隐私标识分为{public}和{private}，缺省为{private}。标识{public}的内容明文输出，标识{private}的内容以\<private>过滤回显。 | 219| args | any[] | 否 | 与格式字符串format对应的可变长度参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 | 220 221**示例：** 222 223输出一条FATAL信息，格式字符串为`"%{public}s World %{private}d"`。其中变参`%{public}s`为明文显示的字符串；`%{private}d`为隐私的整型数。 224 225```js 226hilog.fatal(0x0001, "testTag", "%{public}s World %{private}d", "hello", 3); 227``` 228 229字符串`"hello"`填入`%{public}s`，整型数`3`填入`%{private}d`，输出日志： 230 231``` 23208-05 12:21:47.579 2695 2703 F A00001/testTag: hello World <private> 233``` 234 235## hilog.setMinLogLevel<sup>15+</sup> 236 237setMinLogLevel(level: LogLevel): void 238 239设置应用日志打印的最低日志级别，用于拦截低级别日志打印。 240 241需要注意：如果设置的日志级别低于[全局日志级别](../../dfx/hilog.md#查看和设置日志级别)，设置不生效。 242 243**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 244 245**系统能力**：SystemCapability.HiviewDFX.HiLog 246 247**参数：** 248 249| 参数名 | 类型 | 必填 | 说明 | 250| ------ | --------------------- | ---- | ------------------------------------------------------------ | 251| level | [LogLevel](#loglevel) | 是 | 日志级别。 | 252 253**示例：** 254 255以全局日志级别为INFO下，打印5条不同级别的hilog日志，在打印过程中调用两次setMinLogLevel接口为例： 256 257```js 258hilog.info(0x0001, "testTag", 'this is an info level log, id: %{public}d', 1); 259hilog.setMinLogLevel(hilog.LogLevel.WARN); 260hilog.info(0x0001, "testTag", 'this is an info level log, id: %{public}d', 2); 261hilog.error(0x0001, 'testTag', 'this is an error level log, id: %{public}d', 3); 262hilog.setMinLogLevel(hilog.LogLevel.DEBUG); 263hilog.debug(0x0001, "testTag", 'this is a debug level log, id: %{public}d', 4); 264hilog.info(0x0001, "testTag", 'this is an info level log, id: %{public}d', 5); 265``` 266 267由于全局日志起始为INFO，第一条日志可以正常打印。 268 269在设置进程最低可打印日志级别为WARN后，第二条日志不符合该日志级别，第二条日志打印失败，第三条日志可以正常打印。 270 271在设置进程最低日志级别为DEBUG后，但是此时全局日志级别为INFO，所以第四条日志不满足全局日志级别，打印失败，第五条日志可以打印。 272 273<!--RP1--> 274最终打印结果如下所示： 275``` 27608-07 23:50:01.532 13694-13694 A00001/testTag com.example.hilogDemo I this is an info level log, id: 1 27708-07 23:50:01.532 13694-13694 A00001/testTag com.example.hilogDemo E this is an error level log, id: 3 27808-07 23:50:01.532 13694-13694 A00001/testTag com.example.hilogDemo I this is an info level log, id: 5 279``` 280<!--RP1End--> 281 282## 参数格式符 283 284上述接口中，日志打印的格式化参数需按照如下格式打印： 285 286%{[private flag]}specifier 287 288| 隐私标识符（private flag） | 说明 | 289| ------------ | ---- | 290| 无 | 缺省值默认为private，不打印明文参数。 | 291| private | 隐私参数类型，不打印明文参数。 | 292| public | 明文显示参数。 | 293 294| 格式说明符（specifier） | 说明 | 示例 | 295| ------------ | ---- | ---- | 296| d/i | 支持打印number和bigint类型。 | 123 | 297| s | 支持打印string undefined bool 和null类型。 | "123" | 298| o/O | 支持打印object、undefined和null类型。<br>从API version 20开始，支持该能力。 | { 'name': "Jack", 'age': 22 } | 299 300**示例：** 301```js 302let testObj: Record<string, string | number> = { 303 'name': "Jack", 304 'age': 22 305} 306let isBol = true; 307let bigNum = BigInt(1234567890123456789); 308hilog.info(0x0001, "jsHilogTest", "print object: %{public}s", JSON.stringify(testObj)); 309hilog.info(0x0001, "jsHilogTest", "print object: %{public}o", testObj); 310hilog.info(0x0001, "jsHilogTest", "private flag: %{private}s %s, print null: %{public}s", "hello", "world", null); 311hilog.info(0x0001, "jsHilogTest", "print undefined: %{public}s", undefined); 312hilog.info(0x0001, "jsHilogTest", "print number: %{public}d %{public}i", 123, 456); 313hilog.info(0x0001, "jsHilogTest", "print bigNum: %{public}d %{public}i", bigNum, bigNum); 314hilog.info(0x0001, "jsHilogTest", "print boolean: %{public}s", isBol); 315``` 316 317**打印结果：** 318``` 31908-09 13:26:29.094 2266 2266 I A00001/jsHilogTest: print object: {"name":"Jack","age":22} 32008-09 13:26:29.094 2266 2266 I A00001/jsHilogTest: print object: {"name":"Jack","age":22} 32108-09 13:26:29.094 2266 2266 I A00001/jsHilogTest: private flag: <private> <private>, print null: null 32208-09 13:26:29.094 2266 2266 I A00001/jsHilogTest: print undefined: undefined 32308-09 13:26:29.094 2266 2266 I A00001/jsHilogTest: print number: 123 456 32408-09 13:26:29.095 2266 2266 I A00001/jsHilogTest: print bigNum: 1234567890123456768 1234567890123456768 32508-09 13:26:29.095 2266 2266 I A00001/jsHilogTest: print boolean: true 326```