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