1# @ohos.hiTraceMeter (性能打点) 2 3<!--Kit: Performance Analysis Kit--> 4<!--Subsystem: HiviewDFX--> 5<!--Owner: @qq_437963121--> 6<!--Designer: @kutcherzhou1; @MontSaintMichel--> 7<!--Tester: @gcw_KuLfPSbe--> 8<!--Adviser: @foryourself--> 9 10本模块提供了跟踪进程轨迹，度量程序执行性能的打点能力。本模块打点的数据供hiTraceMeter工具分析使用。 11详细开发流程请参考：[性能打点跟踪开发指导](../../dfx/hitracemeter-guidelines-arkts.md)。 12 13> **说明：** 14> 15> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 16> 17> 建议使用API version 19的性能打点接口，后续性能打点接口[startTrace()](#hitracemeterstarttrace)、[finishTrace()](#hitracemeterfinishtrace)、[traceByValue()](#hitracemetertracebyvalue)将逐步废弃。 18> 19> 性能打点接口[startTrace()](#hitracemeterstarttrace)、[finishTrace()](#hitracemeterfinishtrace)、[traceByValue()](#hitracemetertracebyvalue)无法指定跟踪输出级别，默认均为COMMERCIAL级别性能打点。 20> 21> [用户态trace格式](../../dfx/hitracemeter-view.md#用户态trace格式说明)使用竖线 `|` 作为分隔符，所以通过性能打点接口传递的字符串类型参数应避免包含该字符，防止trace解析异常。 22> 23> [用户态trace](../../dfx/hitracemeter-view.md#用户态trace格式说明)总长度限制512字符，超过的部分将会被截断。 24 25## 导入模块 26 27```js 28import { hiTraceMeter } from '@kit.PerformanceAnalysisKit'; 29``` 30 31## hiTraceMeter.startTrace 32 33startTrace(name: string, taskId: number): void 34 35标记一个异步跟踪耗时任务的开始。 36 37如果有多个相同name的任务需要跟踪或者对同一个任务要跟踪多次，并且任务同时被执行，则开发者每次调用startTrace传入的taskId需不同。 38 39如果具有相同name的任务是串行执行的，则taskId可以相同。具体示例可参考[finishTrace()](#hitracemeterfinishtrace)中的示例。 40 41从API version 19开始，建议使用[startAsyncTrace()](#hitracemeterstartasynctrace19)接口（需与[finishAsyncTrace()](#hitracemeterfinishasynctrace19)接口配套使用），以便分级控制跟踪输出与跟踪聚类。 42 43**原子化服务API**：从API version 19开始，该接口支持在原子化服务中使用。 44 45**系统能力**：SystemCapability.HiviewDFX.HiTrace 46 47**参数：** 48 49| 参数名 | 类型 | 必填 | 说明 | 50| ------ | ------ | ---- | ------------------ | 51| name | string | 是 | 要跟踪的任务名称。 | 52| taskId | number | 是 | 任务id。 | 53 54**示例：** 55 56```js 57hiTraceMeter.startTrace("myTestFunc", 1); 58``` 59 60## hiTraceMeter.finishTrace 61 62finishTrace(name: string, taskId: number): void 63 64标记一个异步跟踪耗时任务的结束。 65 66finishTrace的name和taskId必须与流程开始的[startTrace()](#hitracemeterstarttrace)对应参数值一致。 67 68从API version 19开始，建议使用[finishAsyncTrace()](#hitracemeterfinishasynctrace19)接口（需与[startAsyncTrace()](#hitracemeterstartasynctrace19)接口配套使用）。 69 70**原子化服务API**：从API version 19开始，该接口支持在原子化服务中使用。 71 72**系统能力**：SystemCapability.HiviewDFX.HiTrace 73 74**参数：** 75 76| 参数名 | 类型 | 必填 | 说明 | 77| ------ | ------ | ---- | ------------------ | 78| name | string | 是 | 要跟踪的任务名称。 | 79| taskId | number | 是 | 任务id。 | 80 81**示例：** 82 83```js 84hiTraceMeter.finishTrace("myTestFunc", 1); 85``` 86 87```js 88// 跟踪并行执行的同名任务 89hiTraceMeter.startTrace("myTestFunc", 1); 90// 业务流程...... 91hiTraceMeter.startTrace("myTestFunc", 2); // 第二个跟踪的任务开始，同时第一个跟踪的同名任务还没结束，出现了并行执行，对应接口的taskId需要不同 92// 业务流程...... 93hiTraceMeter.finishTrace("myTestFunc", 1); 94// 业务流程...... 95hiTraceMeter.finishTrace("myTestFunc", 2); 96``` 97 98```js 99// 跟踪串行执行的同名任务 100hiTraceMeter.startTrace("myTestFunc", 1); 101// 业务流程...... 102hiTraceMeter.finishTrace("myTestFunc", 1); // 第一个跟踪的任务结束 103// 业务流程...... 104hiTraceMeter.startTrace("myTestFunc", 1); // 第二个跟踪的同名任务开始，同名的待跟踪任务串行执行。 105// 业务流程...... 106hiTraceMeter.finishTrace("myTestFunc", 1); 107``` 108 109## hiTraceMeter.traceByValue 110 111traceByValue(name: string, count: number): void 112 113用来标记一个跟踪的整数变量，该变量的数值会不断变化。 114 115从API version 19开始，建议使用[traceByValue<sup>19+</sup>()](#hitracemetertracebyvalue19)接口，以便分级控制跟踪输出。 116 117**原子化服务API**：从API version 19开始，该接口支持在原子化服务中使用。 118 119**系统能力**：SystemCapability.HiviewDFX.HiTrace 120 121**参数：** 122 123| 参数名 | 类型 | 必填 | 说明 | 124| ------ | ------ | ---- | ---------------------- | 125| name | string | 是 | 要跟踪的整数变量名称。 | 126| count | number | 是 | 整数变量的值。 | 127 128**示例：** 129 130```js 131let traceCount = 3; 132hiTraceMeter.traceByValue("myTestCount", traceCount); 133traceCount = 4; 134hiTraceMeter.traceByValue("myTestCount", traceCount); 135// 业务流程...... 136``` 137 138## HiTraceOutputLevel<sup>19+</sup> 139 140枚举，跟踪输出级别。 141 142低于系统跟踪输出级别阈值的打点将不会生效。log版本阈值为INFO；nolog版本阈值为COMMERCIAL。 143 144**原子化服务API**：从API version 19开始，该接口支持在原子化服务中使用。 145 146**系统能力**：SystemCapability.HiviewDFX.HiTrace 147 148| 名称 | 值 | 说明 | 149| ---------- | ---- | --------------------------------------- | 150| DEBUG | 0 | 仅用于调试的输出级别，优先级最低。 | 151| INFO | 1 | 用于log版本的输出级别。 | 152| CRITICAL | 2 | 用于log版本的输出级别，优先级高于INFO。 | 153| COMMERCIAL | 3 | 用于nolog版本的输出级别，优先级最高。 | 154| MAX | 3 | 输出级别范围限制，MAX = COMMERCIAL。 | 155 156## hiTraceMeter.startAsyncTrace<sup>19+</sup> 157 158startAsyncTrace(level: HiTraceOutputLevel, name: string, taskId: number, customCategory: string, customArgs?: string): void 159 160标记一个异步跟踪耗时任务的开始，分级控制跟踪输出。 161 162如果有多个相同name的任务需要跟踪或者对同一个任务要跟踪多次，并且任务同时被执行，则开发者每次调用startAsyncTrace传入的taskId需不同。 163 164如果具有相同name的任务是串行执行的，则taskId可以相同。具体示例可参考[finishAsyncTrace()](#hitracemeterfinishasynctrace19)中的示例。 165 166**原子化服务API**：从API version 19开始，该接口支持在原子化服务中使用。 167 168**系统能力**：SystemCapability.HiviewDFX.HiTrace 169 170**参数：** 171 172| 参数名 | 类型 | 必填 | 说明 | 173| -------------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 174| level | [HiTraceOutputLevel](#hitraceoutputlevel19) | 是 | 跟踪输出级别。 | 175| name | string | 是 | 要跟踪的任务名称。 | 176| taskId | number | 是 | 任务id。 | 177| customCategory | string | 是 | 自定义聚类名称，用于聚合同一类异步跟踪打点。 | 178| customArgs | string | 否 | 自定义键值对，格式key=value，多个键值对用逗号分隔。<br>不传入该参数等同于传入空字符串。 | 179 180**示例：** 181 182```js 183// 不需要customCategory参数时，可传入空字符串 184// 不需要customArgs参数时，可不传入该参数或传入空字符串 185const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 186hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 1, "", ""); 187hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 2, ""); 188// 多个键值对用逗号分隔 189hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 3, "categoryTest", "key1=value"); 190hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 4, "categoryTest", "key1=value1,key2=value2"); 191``` 192 193## hiTraceMeter.finishAsyncTrace<sup>19+</sup> 194 195finishAsyncTrace(level: HiTraceOutputLevel, name: string, taskId: number): void 196 197标记一个异步跟踪耗时任务的结束，分级控制跟踪输出。 198 199finishAsyncTrace的level、name和taskId必须与流程开始的[startAsyncTrace()](#hitracemeterstartasynctrace19)对应参数值一致。 200 201**原子化服务API**：从API version 19开始，该接口支持在原子化服务中使用。 202 203**系统能力**：SystemCapability.HiviewDFX.HiTrace 204 205**参数：** 206 207| 参数名 | 类型 | 必填 | 说明 | 208| ------ | ------------------------------------------- | ---- | ------------------ | 209| level | [HiTraceOutputLevel](#hitraceoutputlevel19) | 是 | 跟踪输出级别。 | 210| name | string | 是 | 要跟踪的任务名称。 | 211| taskId | number | 是 | 任务id。 | 212 213**示例：** 214 215```js 216const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 217hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestFunc", 1); 218``` 219 220```js 221const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 222// 跟踪并行执行的同名任务 223// 第一个跟踪的任务开始 224hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 1, "categoryTest", "key=value"); 225// 业务流程...... 226// 第二个跟踪的任务开始，同时第一个跟踪的同名任务还没结束，出现了并行执行，对应接口的taskId需要不同 227hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 2, "categoryTest", "key=value"); 228// 业务流程...... 229// 第一个跟踪的任务结束 230hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestFunc", 1); 231// 业务流程...... 232// 第二个跟踪的任务结束 233hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestFunc", 2); 234``` 235 236```js 237const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 238// 跟踪串行执行的同名任务 239// 第一个跟踪的任务开始 240hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 1, "categoryTest", "key=value"); 241// 业务流程...... 242// 第一个跟踪的任务结束 243hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestFunc", 1); 244// 业务流程...... 245// 第二个跟踪的同名任务开始，同名的待跟踪任务串行执行 246hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 1, "categoryTest", "key=value"); 247// 业务流程...... 248// 第二个跟踪的同名任务结束 249hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestFunc", 1); 250``` 251 252## hiTraceMeter.startSyncTrace<sup>19+</sup> 253 254startSyncTrace(level: HiTraceOutputLevel, name: string, customArgs?: string): void 255 256标记一个同步跟踪耗时任务的开始，分级控制跟踪输出。具体示例可参考[finishSyncTrace()](#hitracemeterfinishsynctrace19)中的示例。 257 258**原子化服务API**：从API version 19开始，该接口支持在原子化服务中使用。 259 260**系统能力**：SystemCapability.HiviewDFX.HiTrace 261 262**参数：** 263 264| 参数名 | 类型 | 必填 | 说明 | 265| ---------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 266| level | [HiTraceOutputLevel](#hitraceoutputlevel19) | 是 | 跟踪输出级别。 | 267| name | string | 是 | 要跟踪的任务名称。 | 268| customArgs | string | 否 | 键值对，格式key=value，多个键值对用逗号分隔。<br>不传入该参数等同于传入空字符串。 | 269 270**示例：** 271 272```js 273const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 274// 不需要customArgs参数时，可不传入该参数或传入空字符串 275hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc"); 276hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc", ""); 277// 多个键值对用逗号分隔 278hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc", "key=value"); 279hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc", "key1=value1,key2=value2"); 280``` 281 282## hiTraceMeter.finishSyncTrace<sup>19+</sup> 283 284finishSyncTrace(level: HiTraceOutputLevel): void 285 286标记一个同步跟踪耗时任务的结束，分级控制跟踪输出。 287 288finishSyncTrace的level必须与流程开始的[startSyncTrace()](#hitracemeterstartsynctrace19)对应参数值一致。 289 290**原子化服务API**：从API version 19开始，该接口支持在原子化服务中使用。 291 292**系统能力**：SystemCapability.HiviewDFX.HiTrace 293 294**参数：** 295 296| 参数名 | 类型 | 必填 | 说明 | 297| ------ | ------------------------------------------- | ---- | -------------- | 298| level | [HiTraceOutputLevel](#hitraceoutputlevel19) | 是 | 跟踪输出级别。 | 299 300**示例：** 301 302```js 303const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 304hiTraceMeter.finishSyncTrace(COMMERCIAL); 305``` 306 307```js 308const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 309// 可嵌套使用，相邻的startSyncTrace与finishSyncTrace匹配 310// 第一个跟踪的任务开始 311hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc1", "key=value"); 312// 业务流程...... 313// 第二个跟踪的任务开始 314hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc2", "key=value"); 315// 业务流程...... 316// 第二个跟踪的任务结束 317hiTraceMeter.finishSyncTrace(COMMERCIAL); 318// 业务流程...... 319// 第一个跟踪的任务结束 320hiTraceMeter.finishSyncTrace(COMMERCIAL); 321``` 322 323## hiTraceMeter.traceByValue<sup>19+</sup> 324 325traceByValue(level: HiTraceOutputLevel, name: string, count: number): void 326 327整数跟踪事件，分级控制跟踪输出。用来标记一个预跟踪的整数变量名及整数值。 328 329**原子化服务API**：从API version 19开始，该接口支持在原子化服务中使用。 330 331**系统能力**：SystemCapability.HiviewDFX.HiTrace 332 333**参数：** 334 335| 参数名 | 类型 | 必填 | 说明 | 336| ------ | ------------------------------------------- | ---- | ---------------------- | 337| level | [HiTraceOutputLevel](#hitraceoutputlevel19) | 是 | 跟踪输出级别。 | 338| name | string | 是 | 要跟踪的整数变量名称。 | 339| count | number | 是 | 整数变量的值。 | 340 341**示例：** 342 343```js 344const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL; 345let traceCount = 3; 346hiTraceMeter.traceByValue(COMMERCIAL, "myTestCount", traceCount); 347traceCount = 4; 348hiTraceMeter.traceByValue(COMMERCIAL, "myTestCount", traceCount); 349// 业务流程...... 350``` 351 352## hiTraceMeter.isTraceEnabled<sup>19+</sup> 353 354isTraceEnabled(): boolean 355 356判断当前是否开启应用trace捕获。 357 358**原子化服务API**：从API version 19开始，该接口支持在原子化服务中使用。 359 360**系统能力**：SystemCapability.HiviewDFX.HiTrace 361 362**返回值：** 363 364| 类型 | 说明 | 365| ------- | ------------------------------------------------------------ | 366| boolean | 使用[hitrace](../../dfx/hitrace.md)命令行工具等方式开启采集时返回true。未开启采集或停止采集后返回false，此时调用HiTraceMeter性能跟踪打点接口无效。 | 367 368**示例：** 369 370```js 371if (hiTraceMeter.isTraceEnabled()) { 372 // 业务流程...... 373} else { 374 // 业务流程...... 375} 376``` 377