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