1# @ohos.hilog (HiLog)
2
3The HiLog subsystem allows your applications or services to output logs based on the specified type, level, and format string. Such logs help you learn the running status of applications and better debug programs.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9## Modules to Import
10
11```js
12import { hilog } from '@kit.PerformanceAnalysisKit';
13```
14
15## hilog.isLoggable
16
17isLoggable(domain: number, tag: string, level: LogLevel) : boolean
18
19Checks whether logs are printable based on the specified service domain, log tag, and log level.
20
21**Atomic service API**: This API can be used in atomic services since API version 11.
22
23**System capability**: SystemCapability.HiviewDFX.HiLog
24
25**Parameters**
26
27| Name| Type                 | Mandatory| Description                                                        |
28| ------ | --------------------- | ---- | ------------------------------------------------------------ |
29| domain | number                | Yes  | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.<br>You can define the value as required.|
30| tag    | string                | Yes  | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur.|
31| level  | [LogLevel](#loglevel) | Yes  | Log level.                                                  |
32
33**Return value**
34
35| Type   | Description                                                        |
36| ------- | ------------------------------------------------------------ |
37| boolean | Returns **true** logs are printable based on the specified service domain, log tag, and log level; returns **false** otherwise.|
38
39**Example**
40
41```js
42hilog.isLoggable(0x0001, "testTag", hilog.LogLevel.INFO);
43```
44
45## LogLevel
46
47Log level.
48
49**Atomic service API**: This API can be used in atomic services since API version 11.
50
51**System capability**: SystemCapability.HiviewDFX.HiLog
52
53| Name |   Value  | Description                                                        |
54| ----- | ------ | ------------------------------------------------------------ |
55| DEBUG | 3      | Log level used to record more detailed process information than INFO logs to help developers analyze service processes and locate faults.|
56| INFO  | 4      | Log level used to record key service process nodes and exceptions that occur during service running,<br>for example, no network signal or login failure.<br>These logs should be recorded by the dominant module in the service to avoid repeated logging conducted by multiple invoked modules or low-level functions.|
57| WARN  | 5      | Log level used to record severe, unexpected faults that have little impact on users and can be rectified by the programs themselves or through simple operations.|
58| ERROR | 6      | Log level used to record program or functional errors that affect the normal running or use of the functionality and can be fixed at a high cost, for example, by resetting data.|
59| FATAL | 7      | Log level used to record program or functionality crashes that cannot be rectified.              |
60
61## hilog.debug
62
63debug(domain: number, tag: string, format: string, ...args: any[]) : void
64
65Prints DEBUG logs.
66
67DEBUG logs are not recorded in official versions by default. They are available in debug versions or in official versions with the debug function enabled.
68
69**Atomic service API**: This API can be used in atomic services since API version 11.
70
71**System capability**: SystemCapability.HiviewDFX.HiLog
72
73**Parameters**
74
75| Name| Type  | Mandatory| Description                                                        |
76| ------ | ------ | ---- | ------------------------------------------------------------ |
77| domain | number | Yes  | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.<br>You can define the value as required.|
78| tag    | string | Yes  | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur.|
79| format | string | Yes  | Format string used to output logs in a specified format. It can contain several elements, where the parameter type and privacy identifier are mandatory.<br>Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **\<private>**.|
80| args   | any[]  | No  | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.|
81
82**Example**
83
84This example is used to output a DEBUG log with the format string being `"%{public}s World %{private}d"`. The variable `%{public}s` is a plaintext string, and the variable `%{private}d` is a private integer.
85
86```js
87hilog.debug(0x0001, "testTag", "%{public}s World %{private}d", "hello", 3);
88```
89
90If `"hello"` is filled in `%{public}s` and `3` in `%{private}d`, the output log is as follows:
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
100Prints INFO logs.
101
102**Atomic service API**: This API can be used in atomic services since API version 11.
103
104**System capability**: SystemCapability.HiviewDFX.HiLog
105
106**Parameters**
107
108| Name| Type  | Mandatory| Description                                                        |
109| ------ | ------ | ---- | ------------------------------------------------------------ |
110| domain | number | Yes  | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.<br>You can define the value as required. |
111| tag    | string | Yes  | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur.|
112| format | string | Yes  | Format string used to output logs in a specified format. It can contain several elements, where the parameter type and privacy identifier are mandatory.<br>Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **\<private>**.|
113| args   | any[]  | No  | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.|
114
115**Example**
116
117This example is used to output an INFO log with the format string being `"%{public}s World %{private}d"`. The variable `%{public}s` is a plaintext string, and the variable `%{private}d` is a private integer.
118
119```js
120hilog.info(0x0001, "testTag", "%{public}s World %{private}d", "hello", 3);
121```
122
123If `"hello"` is filled in `%{public}s` and `3` in `%{private}d`, the output log is as follows:
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
133Prints WARN logs.
134
135**Atomic service API**: This API can be used in atomic services since API version 11.
136
137**System capability**: SystemCapability.HiviewDFX.HiLog
138
139**Parameters**
140
141| Name| Type  | Mandatory| Description                                                        |
142| ------ | ------ | ---- | ------------------------------------------------------------ |
143| domain | number | Yes  | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.<br>You can define the value as required. |
144| tag    | string | Yes  | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur.|
145| format | string | Yes  | Format string used to output logs in a specified format. It can contain several elements, where the parameter type and privacy identifier are mandatory.<br>Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **\<private>**.|
146| args   | any[]  | No  | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.|
147
148**Example**
149
150This example is used to output a WARN log with the format string being `"%{public}s World %{private}d"`. The variable `%{public}s` is a plaintext string, and the variable `%{private}d` is a private integer.
151
152```js
153hilog.warn(0x0001, "testTag", "%{public}s World %{private}d", "hello", 3);
154```
155
156If `"hello"` is filled in `%{public}s` and `3` in `%{private}d`, the output log is as follows:
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
166Prints ERROR logs.
167
168**Atomic service API**: This API can be used in atomic services since API version 11.
169
170**System capability**: SystemCapability.HiviewDFX.HiLog
171
172**Parameters**
173
174| Name| Type  | Mandatory| Description                                                        |
175| ------ | ------ | ---- | ------------------------------------------------------------ |
176| domain | number | Yes  | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.<br>You can define the value as required. |
177| tag    | string | Yes  | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur.|
178| format | string | Yes  | Format string used to output logs in a specified format. It can contain several elements, where the parameter type and privacy identifier are mandatory.<br>Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **\<private>**.|
179| args   | any[]  | No  | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.|
180
181**Example**
182
183This example is used to output an ERROR log with the format string being `"%{public}s World %{private}d"`. The variable `%{public}s` is a plaintext string, and the variable `%{private}d` is a private integer.
184
185```js
186hilog.error(0x0001, "testTag", "%{public}s World %{private}d", "hello", 3);
187```
188
189If `"hello"` is filled in `%{public}s` and `3` in `%{private}d`, the output log is as follows:
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
199Prints FATAL logs.
200
201**Atomic service API**: This API can be used in atomic services since API version 11.
202
203**System capability**: SystemCapability.HiviewDFX.HiLog
204
205**Parameters**
206
207| Name| Type  | Mandatory| Description                                                        |
208| ------ | ------ | ---- | ------------------------------------------------------------ |
209| domain | number | Yes  | Service domain of logs. The value ranges from **0x0** to **0xFFFF**.<br>You can define the value as required. |
210| tag    | string | Yes  | Log tag in the string format. You are advised to use this parameter to identify a particular service behavior or the class holding the ongoing method. A tag can contain a maximum of 31 bytes. If a tag exceeds this limit, it will be truncated. Chinese characters are not recommended because garbled characters or alignment problems may occur.|
211| format | string | Yes  | Format string used to output logs in a specified format. It can contain several elements, where the parameter type and privacy identifier are mandatory.<br>Parameters labeled **{public}** are public data and are displayed in plaintext; parameters labeled **{private}** (default value) are private data and are filtered by **\<private>**.|
212| args   | any[]  | No  | Variable-length parameter list corresponding to the format string. The number and type of parameters must map to the identifier in the format string.|
213
214**Example**
215
216This example is used to output a FATAL log with the format string being `"%{public}s World %{private}d"`. The variable `%{public}s` is a plaintext string, and the variable `%{private}d` is a private integer.
217
218```js
219hilog.fatal(0x0001, "testTag", "%{public}s World %{private}d", "hello", 3);
220```
221
222If `"hello"` is filled in `%{public}s` and `3` in `%{private}d`, the output log is as follows:
223
224```
22508-05 12:21:47.579  2695 2703 F A00001/testTag: hello World <private>
226```
227
228## Parameter Format
229
230Parameters in the log are printed in the following format:
231
232%{[private flag]}specifier
233
234|  Privacy Flag| Description|
235| ------------ | ---- |
236|      Unspecified     | The default value is **private**, indicating that parameters in plaintext are not printed.|
237|  private     | Prints private parameters.|
238|  public      | Prints parameters in plaintext.|
239
240| Specifier| Description| Example|
241| ------------ | ---- | ---- |
242|      d/i      | Prints logs of the **number** and **bigint** types.| 123 |
243|   s     | Prints logs of the **string undefined bool** and **null** types.| "123" |
244
245**Example**
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
261Log printing result:
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```
270