1# @ohos.hiTraceChain (分布式跟踪) 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本模块提供了端侧业务流程调用链跟踪的打点能力，包括业务流程跟踪的启动、结束、信息埋点等能力。 11 12> **说明：** 13> 14> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15 16## 导入模块 17 18```ts 19import { hiTraceChain } from '@kit.PerformanceAnalysisKit'; 20``` 21 22## HiTraceFlag 23 24跟踪标志组合类型枚举。 25 26**系统能力**：以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiTrace。 27 28| 名称 | 值 | 说明 | 29| -------- | -------- | -------- | 30| DEFAULT | 0 | 缺省标志。 | 31| INCLUDE_ASYNC | 1 | 异步调用标志。<br/>设置该标志，同时跟踪同步和异步调用；缺省只跟踪同步调用。 | 32| DONOT_CREATE_SPAN | 1 << 1 | 无分支标志。<br/>设置该标志，不创建分支信息；缺省创建分支信息。 | 33| TP_INFO | 1 << 2 | 埋点标志。<br/>调试场景下设置该标志，调用信息埋点接口[tracepoint()](#hitracechaintracepoint)时，会打印埋点信息hilog日志；缺省不打印埋点信息hilog日志。 | 34| NO_BE_INFO | 1 << 3 | 无开始结束信息标志。<br/>调试场景下设置该标志，调用开始跟踪接口[begin()](#hitracechainbegin)和结束跟踪接口[end()](#hitracechainend)时，分别会打印开始、结束跟踪信息hilog日志；缺省不打印开始、结束跟踪信息hilog日志。 | 35| DISABLE_LOG | 1 << 4 | 日志关联标志。<br/>设置该标志，不会在hilog日志中附加HiTraceId信息；缺省会在hilog日志中附加HiTraceId信息。 | 36| FAILURE_TRIGGER | 1 << 5 | 故障触发标志。预置标志，暂未启用。 | 37| D2D_TP_INFO | 1 << 6 | 设备间埋点标志。TP_INFO的一个子集，调试场景下使用。<br>当已设置TP_INFO标志时，D2D_TP_INFO标志不生效；<br>当未设置TP_INFO标志时，设置D2D_TP_INFO标志，此时调用信息埋点接口[tracepoint()](#hitracechaintracepoint)，仅当mode参数为设备间通信DEVICE的情况下，会打印埋点信息hilog日志。 | 38 39## HiTraceTracepointType 40 41跟踪埋点类型枚举。 42 43**系统能力**：以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiTrace。 44 45| 名称 | 值 | 说明 | 46| -------- | -------- | -------- | 47| CS | 0 | 客户端发送。 | 48| CR | 1 | 客户端接收。 | 49| SS | 2 | 服务端发送。 | 50| SR | 3 | 服务端接收。 | 51| GENERAL | 4 | 通用类型，标识CS、CR、SS、SR四种场景之外的埋点。| 52 53## HiTraceCommunicationMode 54 55跟踪通信类型枚举。 56 57**系统能力**：以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiTrace。 58 59| 名称 | 值 | 说明 | 60| -------- | -------- | -------- | 61| DEFAULT | 0 | 缺省通信类型。 | 62| THREAD | 1 | 线程间通信。 | 63| PROCESS | 2 | 进程间通信。 | 64| DEVICE | 3 | 设备间通信。 | 65 66## HiTraceId 67 68此接口为HiTraceId对象接口。 69 70**系统能力**：以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiTrace。 71 72| 名称 | 类型 | 只读 | 可选 | 说明 | 73| -------- | -------- | -------- | -------- | -------- | 74| chainId | bigint | 否 | 否 | 跟踪链标识。 | 75| spanId | number | 否 | 是 | 分支标识，默认值为0。 | 76| parentSpanId | number | 否 | 是 | 父分支标识，默认值为0。 | 77| flags | number | 否 | 是 | 跟踪标志位，默认值为0。 | 78 79## hiTraceChain.begin 80 81begin(name: string, flags?: number): HiTraceId 82 83开始跟踪，同步接口。 84 85当前线程TLS（Thread Local Storage，线程本地存储）中不存在有效的HiTraceId时，生成有效的HiTraceId并设置到当前线程TLS中，返回该HiTraceId。 86 87当前线程TLS中已存在有效的HiTraceId时，不会开始新的跟踪，返回各属性值均为0的无效HiTraceId。 88 89**系统能力**：SystemCapability.HiviewDFX.HiTrace 90 91**参数：** 92 93| 参数名 | 类型 | 必填 | 说明 | 94| -------- | -------- | -------- | -------- | 95| name | string | 是 | 跟踪业务名。 | 96| flags | number | 否 | 跟踪标志组合，具体可参考[HiTraceFlag](#hitraceflag)，默认值为0。 | 97 98**返回值：** 99 100| 类型 | 说明 | 101| -------- | -------- | 102| [HiTraceId](#hitraceid) | HiTraceId实例。 | 103 104**示例：** 105 106```ts 107// 开始跟踪，跟踪标志是INCLUDE_ASYNC与DONOT_CREATE_SPAN的并集。 108let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 109// 若干业务逻辑完成后，结束跟踪。 110hiTraceChain.end(traceId); 111``` 112 113## hiTraceChain.end 114 115end(id: HiTraceId): void 116 117结束跟踪，同步接口。 118 119若给定的HiTraceId有效，且等于当前线程TLS中的HiTraceId，结束跟踪并将当前线程TLS中的HiTraceId设置为无效。 120 121若给定的HiTraceId无效，或不等于当前线程TLS中的HiTraceId，结束跟踪失败，打印结束跟踪失败hilog日志。 122 123**系统能力**：SystemCapability.HiviewDFX.HiTrace 124 125**参数：** 126 127| 参数名 | 类型 | 必填 | 说明 | 128| -------- | -------- | -------- | -------- | 129| id | [HiTraceId](#hitraceid) | 是 | HiTraceId实例。 | 130 131**示例：** 132 133```ts 134// 开始跟踪，跟踪标志是DEFAULT。 135let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 136// 若干业务逻辑完成后，结束跟踪。 137hiTraceChain.end(traceId); 138``` 139 140## hiTraceChain.getId 141 142getId(): HiTraceId 143 144获取跟踪标识，同步接口。 145 146获取当前线程TLS中的HiTraceId。 147 148**系统能力**：SystemCapability.HiviewDFX.HiTrace 149 150**返回值：** 151 152| 类型 | 说明 | 153| -------- | -------- | 154| [HiTraceId](#hitraceid) | HiTraceId实例。 | 155 156**示例：** 157 158```ts 159// 开始跟踪，跟踪标志是DEFAULT。 160let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 161// 若干业务逻辑完成后，获取当前跟踪标识。 162let curTraceId = hiTraceChain.getId(); 163// 同一跟踪链获取的跟踪标识的chainId一定相同。 164if (curTraceId.chainId != traceId.chainId) { 165// 基于异常场景的处理逻辑。 166} 167// 若干业务逻辑完成后，结束跟踪。 168hiTraceChain.end(traceId); 169``` 170 171## hiTraceChain.setId 172 173setId(id: HiTraceId): void 174 175设置跟踪标识，同步接口。 176 177将给定的HiTraceId设置到当前线程TLS中。若给定的HiTraceId无效，则不执行任何操作。 178 179**系统能力**：SystemCapability.HiviewDFX.HiTrace 180 181**参数：** 182 183| 参数名 | 类型 | 必填 | 说明 | 184| -------- | -------- | -------- | -------- | 185| id | [HiTraceId](#hitraceid) | 是 | HiTraceId实例。 | 186 187**示例：** 188 189```ts 190// 获取当前跟踪链中的跟踪标识。 191let traceId = hiTraceChain.getId(); 192// 将获取的跟踪标识设置为当前traceId。 193hiTraceChain.setId(traceId); 194``` 195 196## hiTraceChain.clearId 197 198clearId(): void 199 200清除跟踪标识，同步接口。 201 202将当前线程TLS中的HiTraceId设置为无效。 203 204**系统能力**：SystemCapability.HiviewDFX.HiTrace 205 206**示例：** 207 208```ts 209// 业务开始前，尝试清除跟踪标识。 210hiTraceChain.clearId(); 211// 开始跟踪，跟踪标志是DEFAULT。 212let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 213// 若干业务逻辑完成后，结束跟踪。 214hiTraceChain.end(traceId); 215``` 216 217## hiTraceChain.createSpan 218 219createSpan(): HiTraceId 220 221创建跟踪分支，同步接口。 222 223创建一个HiTraceId，使用当前线程TLS中的chainId、spanId初始化HiTraceId的chainId、parentSpanId，并为HiTraceId生成一个新的spanId，返回该HiTraceId。 224 225**系统能力**：SystemCapability.HiviewDFX.HiTrace 226 227**返回值：** 228 229| 类型 | 说明 | 230| -------- | -------- | 231| [HiTraceId](#hitraceid) | HiTraceId实例。 | 232 233**示例：** 234 235```ts 236// 开始跟踪，跟踪标志是DEFAULT。 237let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 238// 若干业务逻辑完成后，创建跟踪分支。 239let spanTraceId = hiTraceChain.createSpan(); 240// 同一跟踪链的跟踪标识的chainId一定相同。 241if (spanTraceId.chainId != traceId.chainId) { 242// 基于异常场景的处理逻辑。 243} 244//业务结束，结束跟踪。 245hiTraceChain.end(traceId); 246``` 247 248## hiTraceChain.tracepoint 249 250tracepoint(mode: HiTraceCommunicationMode, type: HiTraceTracepointType, id: HiTraceId, msg?: string): void 251 252[HiTraceMeter](./js-apis-hitracemeter.md)跟踪信息埋点，同步接口。 253 254当type为客户端发送CS和服务端接收SC时，进行同步HiTraceMeter开始打点；当type为客户端接收CC和服务端发送SS时，进行同步HiTraceMeter结束打点；当type为通用类型GENERAL时，不会进行HiTraceMeter打点。 255 256type为客户端发送CS和客户端接收CC的信息埋点需配套使用；type为服务端接收SC和服务端发送SS的信息埋点需配套使用。否则，HiTraceMeter开始与结束打点无法正常匹配。 257 258**系统能力**：SystemCapability.HiviewDFX.HiTrace 259 260**参数：** 261 262| 参数名 | 类型 | 必填 | 说明 | 263| -------- | -------- | -------- | -------- | 264| mode | [HiTraceCommunicationMode](#hitracecommunicationmode) | 是 | 信息埋点需要指定的跟踪通信模式。 | 265| type | [HiTraceTracepointType](#hitracetracepointtype)| 是 | 信息埋点需要指定的跟踪埋点类型。 | 266| id | [HiTraceId](#hitraceid) | 是 | 实施信息埋点操作的HiTraceId实例。 | 267| msg | string | 否 | HiTraceMeter打点操作传入的trace说明信息。 | 268 269**示例：** 270 271```ts 272// 开始跟踪，跟踪标志是INCLUDE_ASYNC与DONOT_CREATE_SPAN的并集。 273let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 274// 若干业务逻辑完成后，触发信息埋点操作。 275hiTraceChain.tracepoint(hiTraceChain.HiTraceCommunicationMode.THREAD, hiTraceChain.HiTraceTracepointType.SS, traceId, "Just a example"); 276//业务结束，结束跟踪。 277hiTraceChain.end(traceId); 278``` 279 280## hiTraceChain.isValid 281 282isValid(id: HiTraceId): boolean 283 284判断HiTraceId是否有效，同步接口。 285 286**系统能力**：SystemCapability.HiviewDFX.HiTrace 287 288**参数：** 289 290| 参数名 | 类型 | 必填 | 说明 | 291| -------- | -------- | -------- | -------- | 292| id | [HiTraceId](#hitraceid) | 是 | 需要判断是否有效的HiTraceId实例。 | 293 294**返回值：** 295 296| 类型 | 说明 | 297| -------- | -------- | 298| boolean | true：HiTraceId有效；false：HiTraceId无效。 | 299 300**示例：** 301 302```ts 303// 开始跟踪，跟踪标志是DEFAULT。 304let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 305// traceIdIsvalid为true 306let traceIdIsvalid = hiTraceChain.isValid(traceId); 307if (traceIdIsvalid) { 308// 基于跟踪标识合法性校验成功的场景的处理逻辑。 309} 310//业务结束，结束跟踪。 311hiTraceChain.end(traceId); 312``` 313 314## hiTraceChain.isFlagEnabled 315 316isFlagEnabled(id: HiTraceId, flag: HiTraceFlag): boolean 317 318判断HiTraceId是否启用了跟踪标志flag，同步接口。 319 320**系统能力**：SystemCapability.HiviewDFX.HiTrace 321 322**参数：** 323 324| 参数名 | 类型 | 必填 | 说明 | 325| -------- | -------- | -------- | -------- | 326| id | [HiTraceId](#hitraceid) | 是 | 需要判断指定跟踪标志是否启用的HiTraceId实例。 | 327| flag | [HiTraceFlag](#hitraceflag) | 是 | 指定的跟踪标志。 | 328 329**返回值：** 330 331| 类型 | 说明 | 332| -------- | -------- | 333| boolean | true：HiTraceId已启用flag；false：HiTraceId未启用flag。 | 334 335**示例：** 336 337```ts 338// 开始跟踪，跟踪标志是INCLUDE_ASYNC。 339let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); 340// enabledIncludeAsyncFlag为true。 341let enabledIncludeAsyncFlag = hiTraceChain.isFlagEnabled(traceId, hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); 342if (enabledIncludeAsyncFlag) { 343// 基于INCLUDE_ASYNC跟踪标志已设置场景的处理逻辑。 344} 345//业务结束，结束跟踪。 346hiTraceChain.end(traceId); 347``` 348 349## hiTraceChain.enableFlag 350 351enableFlag(id: HiTraceId, flag: HiTraceFlag): void 352 353启用HiTraceId中指定的跟踪标志，同步接口。 354 355**系统能力**：SystemCapability.HiviewDFX.HiTrace 356 357**参数：** 358 359| 参数名 | 类型 | 必填 | 说明 | 360| -------- | -------- | -------- | -------- | 361| id | [HiTraceId](#hitraceid) | 是 | 需要启用指定跟踪标志的HiTraceId实例。 | 362| flag | [HiTraceFlag](#hitraceflag) | 是 | 指定的跟踪标志。 | 363 364**示例：** 365 366```ts 367// 开始跟踪，跟踪标志是INCLUDE_ASYNC。 368let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); 369// enabledDoNotCreateSpanFlag为false。 370let enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(traceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 371// 设置DONOT_CREATE_SPAN跟踪标志。 372hiTraceChain.enableFlag(traceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 373// enabledDoNotCreateSpanFlag为true。 374enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(traceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 375if (enabledDoNotCreateSpanFlag) { 376// 基于DONOT_CREATE_SPAN跟踪标志已设置场景的处理逻辑。 377} 378//业务结束，结束跟踪。 379hiTraceChain.end(traceId); 380``` 381