1# @ohos.hiTraceMeter (Performance Tracing) 2 3<!--Kit: Performance Analysis Kit--> 4<!--Subsystem: HiviewDFX--> 5<!--Owner: @qq_437963121--> 6<!--SE: @MontSaintMichel--> 7<!--TSE: @gcw_KuLfPSbe--> 8 9The **HiTraceMeter** module provides the functions of tracing service processes and monitoring the system performance. It provides the data needed for HiTraceMeter to carry out performance analysis. 10For details about the development process, see [Using HiTraceMeter](../../dfx/hitracemeter-guidelines-arkts.md). 11 12> **NOTE** 13> 14> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 15> 16> You are advised to use the performance tracing APIs of API version 19. The [startTrace](#hitracemeterstarttrace), [finishTrace](#hitracemeterfinishtrace), and [traceByValue](#hitracemetertracebyvalue) APIs will be deprecated. 17> 18> The trace output level cannot be specified in the [startTrace](#hitracemeterstarttrace), [finishTrace](#hitracemeterfinishtrace) and [traceByValue](#hitracemetertracebyvalue) APIs. By default, the trace output level is **COMMERCIAL**. 19> 20> The vertical bar (|) is used as the separator in [user-mode trace format](../../dfx/hitracemeter-view.md#user-mode-trace-format). Therefore, the string parameters passed by the performance tracing APIs must exclude this character to avoid trace parsing exceptions. 21> 22> The maximum length of a [user-mode trace](../../dfx/hitracemeter-view.md#user-mode-trace-format) is 512 characters. Excess characters will be truncated. 23 24## Modules to Import 25 26```js 27import { hiTraceMeter } from '@kit.PerformanceAnalysisKit'; 28``` 29 30## hiTraceMeter.startTrace 31 32startTrace(name: string, taskId: number): void 33 34Starts an asynchronous trace. 35 36If multiple trace tasks with the same name need to be performed at the same time or a trace needs to be performed multiple times concurrently, different task IDs must be specified in **startTrace**. 37 38If the trace tasks with the same name are not performed at the same time, the same taskId can be used. For a specific example, see [finishTrace](#hitracemeterfinishtrace). 39 40Since API version 19, you are advised to use [startAsyncTrace](#hitracemeterstartasynctrace19), which must be used together with [finishAsyncTrace](#hitracemeterfinishasynctrace19). In this way, you can specify the trace output level and category. 41 42**Atomic service API**: This API can be used in atomic services since API version 19. 43 44**System capability**: SystemCapability.HiviewDFX.HiTrace 45 46**Parameters** 47 48| Name| Type | Mandatory| Description | 49| ------ | ------ | ---- | ------------------ | 50| name | string | Yes | Name of the trace to start.| 51| taskId | number | Yes | Task ID. | 52 53**Example** 54 55```js 56hiTraceMeter.startTrace("myTestFunc", 1); 57``` 58 59## hiTraceMeter.finishTrace 60 61finishTrace(name: string, taskId: number): void 62 63Stops an asynchronous trace. 64 65To stop a trace, the values of name and task ID in **finishTrace** must be the same as those in [startTrace](#hitracemeterstarttrace). 66 67Since API version 19, you are advised to use [finishAsyncTrace](#hitracemeterfinishasynctrace19), which must be used together with [startAsyncTrace](#hitracemeterstartasynctrace19). 68 69**Atomic service API**: This API can be used in atomic services since API version 19. 70 71**System capability**: SystemCapability.HiviewDFX.HiTrace 72 73**Parameters** 74 75| Name| Type | Mandatory| Description | 76| ------ | ------ | ---- | ------------------ | 77| name | string | Yes | Name of the trace to start.| 78| taskId | number | Yes | Task ID. | 79 80**Example** 81 82```js 83hiTraceMeter.finishTrace("myTestFunc", 1); 84``` 85 86```js 87// Start trace tasks with the same name concurrently. 88hiTraceMeter.startTrace("myTestFunc", 1); 89// Service flow... 90hiTraceMeter.startTrace("myTestFunc", 2); // Start the second trace with the same name while the first task is still running. The tasks are running concurrently and therefore their taskId must be different. 91// Service flow... 92hiTraceMeter.finishTrace("myTestFunc", 1); 93// Service flow... 94hiTraceMeter.finishTrace("myTestFunc", 2); 95``` 96 97```js 98// Start trace tasks with the same name in serial mode. 99hiTraceMeter.startTrace("myTestFunc", 1); 100// Service flow... 101hiTraceMeter.finishTrace("myTestFunc", 1); // End the first trace. 102// Service flow... 103hiTraceMeter.startTrace("myTestFunc", 1); // Start the second trace with the same name in serial mode. 104// Service flow... 105hiTraceMeter.finishTrace("myTestFunc", 1); 106``` 107 108## hiTraceMeter.traceByValue 109 110traceByValue(name: string, count: number): void 111 112Traces the value changes of an integer variable. 113 114Since API version 19, you are advised to use the [traceByValue<sup>19+</sup>](#hitracemetertracebyvalue19) API to specify the trace output level 115 116**Atomic service API**: This API can be used in atomic services since API version 19. 117 118**System capability**: SystemCapability.HiviewDFX.HiTrace 119 120**Parameters** 121 122| Name| Type | Mandatory| Description | 123| ------ | ------ | ---- | ---------------------- | 124| name | string | Yes | Name of the integer variable to trace.| 125| count | number | Yes | Value of an integer variable. | 126 127**Example** 128 129```js 130let traceCount = 3; 131hiTraceMeter.traceByValue("myTestCount", traceCount); 132traceCount = 4; 133hiTraceMeter.traceByValue("myTestCount", traceCount); 134// Service flow... 135``` 136 137## HiTraceOutputLevel<sup>19+</sup> 138 139Enumerates trace output levels. 140 141The trace output level lower than the threshold does not take effect. The log version threshold is **INFO**, and the nolog version threshold is **COMMERCIAL**. 142 143**Atomic service API**: This API can be used in atomic services since API version 19. 144 145**System capability**: SystemCapability.HiviewDFX.HiTrace 146 147| Level | Value | Description | 148| ---------- | ---- | --------------------------------------- | 149| DEBUG | 0 | Level used only for debugging, which has the lowest priority. | 150| INFO | 1 | Level for the log version. | 151| CRITICAL | 2 | Level for the log version, which has a higher priority than **INFO**.| 152| COMMERCIAL | 3 | Level for the nolog version, which has the highest priority. | 153| MAX | 3 | Maximum trace output level: **COMMERCIAL**. | 154 155## hiTraceMeter.startAsyncTrace<sup>19+</sup> 156 157startAsyncTrace(level: HiTraceOutputLevel, name: string, taskId: number, customCategory: string, customArgs?: string): void 158 159Starts an asynchronous trace with the trace output level specified. 160 161If multiple trace tasks with the same name need to be performed at the same time or a trace needs to be performed multiple times concurrently, different task IDs must be specified in **startAsyncTrace**. 162 163If the trace tasks with the same name are not performed at the same time, the same taskId can be used. For details, see [finishAsyncTrace](#hitracemeterfinishasynctrace19). 164 165**Atomic service API**: This API can be used in atomic services since API version 19. 166 167**System capability**: SystemCapability.HiviewDFX.HiTrace 168 169**Parameters** 170 171| Name | Type | Mandatory| Description | 172| -------------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 173| level | [HiTraceOutputLevel](#hitraceoutputlevel19) | Yes | Trace output level. | 174| name | string | Yes | Name of the trace to start. | 175| taskId | number | Yes | Task ID. | 176| customCategory | string | Yes | Custom category name, which is used to collect asynchronous trace data of the same type. | 177| customArgs | string | No | Custom key-value pair. The format is **key=value**. Use commas (,) to separate multiple key-value pairs.<br>If this parameter is not passed in, an empty string is passed in.| 178 179**Example** 180 181```js 182// If the customCategory parameter is not required, pass in an empty string. 183// If the customArgs parameter is not required, do not pass in this parameter or pass in an empty string. 184const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 185hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 1, "", ""); 186hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 2, ""); 187// Use commas (,) to separate multiple key-value pairs. 188hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 3, "categoryTest", "key1=value"); 189hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 4, "categoryTest", "key1=value1,key2=value2"); 190``` 191 192## hiTraceMeter.finishAsyncTrace<sup>19+</sup> 193 194finishAsyncTrace(level: HiTraceOutputLevel, name: string, taskId: number): void 195 196Stops an asynchronous trace with the trace output level specified. 197 198The **level**, **name**, and **taskId** used in **finishAsyncTrace** must be the same as those of [startAsyncTrace](#hitracemeterstartasynctrace19). 199 200**Atomic service API**: This API can be used in atomic services since API version 19. 201 202**System capability**: SystemCapability.HiviewDFX.HiTrace 203 204**Parameters** 205 206| Name| Type | Mandatory| Description | 207| ------ | ------------------------------------------- | ---- | ------------------ | 208| level | [HiTraceOutputLevel](#hitraceoutputlevel19) | Yes | Trace output level. | 209| name | string | Yes | Name of the trace to start.| 210| taskId | number | Yes | Task ID. | 211 212**Example** 213 214```js 215const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 216hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestFunc", 1); 217``` 218 219```js 220const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 221// Start trace tasks with the same name concurrently. 222// Start the first trace. 223hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 1, "categoryTest", "key=value"); 224// Service flow... 225// Start the second trace with the same name while the first trace is still running. The tasks are running concurrently and therefore their taskId must be different. 226hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 2, "categoryTest", "key=value"); 227// Service flow... 228// Stop the first trace. 229hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestFunc", 1); 230// Service flow... 231// Stop the second trace. 232hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestFunc", 2); 233``` 234 235```js 236const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 237// Start trace tasks with the same name in serial mode. 238// Start the first trace. 239hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 1, "categoryTest", "key=value"); 240// Service flow... 241// Stop the first trace. 242hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestFunc", 1); 243// Service flow... 244// Start the second trace with the same name. The traces with the same name are executed in serial mode. 245hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 1, "categoryTest", "key=value"); 246// Service flow... 247// Stop the second trace with the same name. 248hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestFunc", 1); 249``` 250 251## hiTraceMeter.startSyncTrace<sup>19+</sup> 252 253startSyncTrace(level: HiTraceOutputLevel, name: string, customArgs?: string): void 254 255Starts a synchronous trace with the trace output level specified. For details, see [finishSyncTrace](#hitracemeterfinishsynctrace19). 256 257**Atomic service API**: This API can be used in atomic services since API version 19. 258 259**System capability**: SystemCapability.HiviewDFX.HiTrace 260 261**Parameters** 262 263| Name | Type | Mandatory| Description | 264| ---------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 265| level | [HiTraceOutputLevel](#hitraceoutputlevel19) | Yes | Trace output level. | 266| name | string | Yes | Name of the trace to start. | 267| customArgs | string | No | Custom key-value pair. The format is **key=value**. Use commas (,) to separate multiple key-value pairs.<br>If this parameter is not passed in, an empty string is passed in.| 268 269**Example** 270 271```js 272const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 273// If the customArgs parameter is not required, do not pass in this parameter or pass in an empty string. 274hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc"); 275hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc", ""); 276// Use commas (,) to separate multiple key-value pairs. 277hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc", "key=value"); 278hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc", "key1=value1,key2=value2"); 279``` 280 281## hiTraceMeter.finishSyncTrace<sup>19+</sup> 282 283finishSyncTrace(level: HiTraceOutputLevel): void 284 285Stops a synchronous trace with the trace output level specified. 286 287The **level** used in **finishSyncTrace** must be the same as that of [startSyncTrace](#hitracemeterstartsynctrace19). 288 289**Atomic service API**: This API can be used in atomic services since API version 19. 290 291**System capability**: SystemCapability.HiviewDFX.HiTrace 292 293**Parameters** 294 295| Name| Type | Mandatory| Description | 296| ------ | ------------------------------------------- | ---- | -------------- | 297| level | [HiTraceOutputLevel](#hitraceoutputlevel19) | Yes | Trace output level.| 298 299**Example** 300 301```js 302const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 303hiTraceMeter.finishSyncTrace(COMMERCIAL); 304``` 305 306```js 307const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 308// The startSyncTrace and finishSyncTrace APIs can be nested and they matched each other based on proximity. 309// Start the first trace. 310hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc1", "key=value"); 311// Service flow... 312// Start the second trace. 313hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc2", "key=value"); 314// Service flow... 315// Stop the second trace. 316hiTraceMeter.finishSyncTrace(COMMERCIAL); 317// Service flow... 318// Stop the first trace. 319hiTraceMeter.finishSyncTrace(COMMERCIAL); 320``` 321 322## hiTraceMeter.traceByValue<sup>19+</sup> 323 324traceByValue(level: HiTraceOutputLevel, name: string, count: number): void 325 326Traces an integer with the trace output level specified. **name** and **count** are used to identify the name and value of an integer variable to be traced. 327 328**Atomic service API**: This API can be used in atomic services since API version 19. 329 330**System capability**: SystemCapability.HiviewDFX.HiTrace 331 332**Parameters** 333 334| Name| Type | Mandatory| Description | 335| ------ | ------------------------------------------- | ---- | ---------------------- | 336| level | [HiTraceOutputLevel](#hitraceoutputlevel19) | Yes | Trace output level. | 337| name | string | Yes | Name of the integer variable to trace.| 338| count | number | Yes | Value of an integer variable. | 339 340**Example** 341 342```js 343const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 344let traceCount = 3; 345hiTraceMeter.traceByValue(COMMERCIAL, "myTestCount", traceCount); 346traceCount = 4; 347hiTraceMeter.traceByValue(COMMERCIAL, "myTestCount", traceCount); 348// Service flow... 349``` 350 351## hiTraceMeter.isTraceEnabled<sup>19+</sup> 352 353isTraceEnabled(): boolean 354 355Checks whether application trace capture is enabled. 356 357You can use [HiTrace](../../dfx/hitrace.md) commands to enable or disable trace capture. 358 359**Atomic service API**: This API can be used in atomic services since API version 19. 360 361**System capability**: SystemCapability.HiviewDFX.HiTrace 362 363**Returns** 364 365| Type | Description | 366| ------- | ------------------------------------------------------------ | 367| boolean | Returns **true** if the application trace capture is enabled and the HiTraceMeter performance tracing takes effect;<br>returns **false** otherwise.| 368 369**Example** 370 371```js 372if (hiTraceMeter.isTraceEnabled()) { 373 // Service flow... 374} else { 375 // Service flow... 376} 377``` 378