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