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**. If the value exceeds the range, logs cannot be printed.<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**. If the value exceeds the range, logs cannot be printed.<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**. If the value exceeds the range, logs cannot be printed.<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**. If the value exceeds the range, logs cannot be printed.<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**. If the value exceeds the range, logs cannot be printed.<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**. If the value exceeds the range, logs cannot be printed.<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## hilog.setMinLogLevel<sup>15+</sup> 229 230setMinLogLevel(level: LogLevel): void 231 232Sets the minimum log level. 233 234If the set log level is lower than the [global log level](../../dfx/hilog.md#displaying-and-setting-log-levels), the setting does not take effect. 235 236**Atomic service API**: This API can be used in atomic services since API version 15. 237 238**System capability**: SystemCapability.HiviewDFX.HiLog 239 240**Parameters** 241 242| Name| Type | Mandatory| Description | 243| ------ | --------------------- | ---- | ------------------------------------------------------------ | 244| level | [LogLevel](#loglevel) | Yes | Log level. | 245 246**Example** 247 248The following example prints five HiLog logs of different levels and calls the **setMinLogLevel** API twice when the global log level is **INFO**: 249 250```js 251hilog.info(0x0001, "testTag", 'this is an info level log, id: %{public}d', 1); 252hilog.setMinLogLevel(hilog.LogLevel.WARN); 253hilog.info(0x0001, "testTag", 'this is an info level log, id: %{public}d', 2); 254hilog.error(0x0001, 'testTag', 'this is an error level log, id: %{public}d', 3); 255hilog.setMinLogLevel(hilog.LogLevel.DEBUG); 256hilog.debug(0x0001, "testTag", 'this is a debug level log, id: %{public}d', 4); 257hilog.info(0x0001, "testTag", 'this is an info level log, id: %{public}d', 5); 258``` 259 260The first log is printed properly because the global log level is **INFO**. 261 262After the minimum log level of the process is set to **WARN**, the second log does not meet the log level and fails to be printed. The third log is printed properly. 263 264After the minimum log level of the process is set to **DEBUG**, the fourth log does not meet the global log level and fails to be printed. The fifth log is printed. 265 266<!--RP1--> 267The log result is as follows: 268``` 26908-07 23:50:01.532 13694-13694 A00001/testTag com.example.hilogDemo I this is an info level log, id: 1 27008-07 23:50:01.532 13694-13694 A00001/testTag com.example.hilogDemo E this is an error level log, id: 3 27108-07 23:50:01.532 13694-13694 A00001/testTag com.example.hilogDemo I this is an info level log, id: 5 272``` 273<!--RP1End--> 274 275## Parameter Format 276 277Parameters in the log are printed in the following format: 278 279%{[private flag]}specifier 280 281| Private Flag| Description| 282| ------------ | ---- | 283| Unspecified | The default value is **private**, indicating that parameters in plaintext are not printed.| 284| private | Prints private parameters.| 285| public | Prints parameters in plaintext.| 286 287| Specifier| Description| Example| 288| ------------ | ---- | ---- | 289| d/i | Prints logs of the **number** and **bigint** types.| 123 | 290| s | Prints logs of the **string undefined bool** and **null** types.| "123" | 291| o/O | Prints logs of the **object**, **undefined**, and **null** types.<br>This specifier is supported since API version 20.| { 'name': "Jack", 'age': 22 } | 292 293**Example** 294```js 295let testObj: Record<string, string | number> = { 296 'name': "Jack", 297 'age': 22 298} 299let isBol = true; 300let bigNum = BigInt(1234567890123456789); 301hilog.info(0x0001, "jsHilogTest", "print object: %{public}s", JSON.stringify(testObj)); 302hilog.info(0x0001, "jsHilogTest", "print object: %{public}o", testObj); 303hilog.info(0x0001, "jsHilogTest", "private flag: %{private}s %s, print null: %{public}s", "hello", "world", null); 304hilog.info(0x0001, "jsHilogTest", "print undefined: %{public}s", undefined); 305hilog.info(0x0001, "jsHilogTest", "print number: %{public}d %{public}i", 123, 456); 306hilog.info(0x0001, "jsHilogTest", "print bigNum: %{public}d %{public}i", bigNum, bigNum); 307hilog.info(0x0001, "jsHilogTest", "print boolean: %{public}s", isBol); 308``` 309 310**Log printing result**: 311``` 31208-09 13:26:29.094 2266 2266 I A00001/jsHilogTest: print object: {"name":"Jack","age":22} 31308-09 13:26:29.094 2266 2266 I A00001/jsHilogTest: print object: {"name":"Jack","age":22} 31408-09 13:26:29.094 2266 2266 I A00001/jsHilogTest: private flag: <private> <private>, print null: null 31508-09 13:26:29.094 2266 2266 I A00001/jsHilogTest: print undefined: undefined 31608-09 13:26:29.094 2266 2266 I A00001/jsHilogTest: print number: 123 456 31708-09 13:26:29.095 2266 2266 I A00001/jsHilogTest: print bigNum: 1234567890123456768 1234567890123456768 31808-09 13:26:29.095 2266 2266 I A00001/jsHilogTest: print boolean: true 319``` 320