1# @ohos.hiTraceChain (分布式跟踪) 2 3本模块提供了端侧业务流程调用链跟踪的打点能力，包括业务流程跟踪的启动、结束、信息埋点等能力。 4 5> **说明：** 6> 7> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```js 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```js 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```js 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```js 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```js 161let asyncTraceId; 162let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 163// 若干业务逻辑完成后，设置当前HiTraceId。 164hiTraceChain.setId(asyncTraceId); 165``` 166 167## hiTraceChain.clearId 168 169clearId(): void 170 171清除跟踪标识，同步接口。 172 173**系统能力：** SystemCapability.HiviewDFX.HiTrace 174 175**示例：** 176 177```js 178let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 179// 若干业务逻辑完成后，清除当前HiTraceId。 180hiTraceChain.clearId(); 181``` 182 183## hiTraceChain.createSpan 184 185createSpan(): HiTraceId 186 187创建跟踪分支，同步接口。 188 189**系统能力：** SystemCapability.HiviewDFX.HiTrace 190 191**返回值：** 192 193| 类型 | 说明 | 194| -------- | -------- | 195| [HiTraceId](#hitraceid) | HiTraceId实例。 | 196 197**示例：** 198 199```js 200let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 201// 若干业务逻辑完成后，创建跟踪分支。 202let spanTraceId = hiTraceChain.createSpan(); 203``` 204 205## hiTraceChain.tracepoint 206 207tracepoint(mode: HiTraceCommunicationMode, type: HiTraceTracepointType, id: HiTraceId, msg?: string): void 208 209信息埋点，同步接口。 210 211**系统能力：** SystemCapability.HiviewDFX.HiTrace 212 213**参数：** 214 215| 参数名 | 类型 | 必填 | 说明 | 216| -------- | -------- | -------- | -------- | 217| mode | [HiTraceCommunicationMode](#hitracecommunicationmode) | 是 | 信息埋点需要指定的跟踪通信模式。 | 218| type | [HiTraceTracepointType](#hitracetracepointtype)| 是 | 信息埋点需要指定的跟踪埋点类型。 | 219| id | [HiTraceId](#hitraceid) | 是 | 实施信息埋点操作的HiTraceId实例。 | 220| msg | string | 否 | 信息埋点操作传入的trace说明信息。 | 221 222**示例：** 223 224```js 225let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 226// 若干业务逻辑完成后，触发信息埋点操作。 227hiTraceChain.tracepoint(hiTraceChain.HiTraceCommunicationMode.THREAD, hiTraceChain.HiTraceTracepointType.SS, asyncTraceId, "Just a example"); 228``` 229 230## hiTraceChain.isValid 231 232isValid(id: HiTraceId): boolean 233 234判断HiTraceId对象是否有效，同步接口。 235 236**系统能力：** SystemCapability.HiviewDFX.HiTrace 237 238**参数：** 239 240| 参数名 | 类型 | 必填 | 说明 | 241| -------- | -------- | -------- | -------- | 242| id | [HiTraceId](#hitraceid) | 是 | 需要判断是否有效的HiTraceId实例。 | 243 244**返回值：** 245 246| 类型 | 说明 | 247| -------- | -------- | 248| boolean | 返回true表示HiTraceId有效，否则无效。 | 249 250**示例：** 251 252```js 253let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 254let traceIdIsvalid = hiTraceChain.isValid(traceId); 255``` 256 257## hiTraceChain.isFlagEnabled 258 259isFlagEnabled(id: HiTraceId, flag: HiTraceFlag): boolean 260 261判断HiTraceId对象中指定的跟踪标志是否已置位，同步接口。 262 263**系统能力：** SystemCapability.HiviewDFX.HiTrace 264 265**参数：** 266 267| 参数名 | 类型 | 必填 | 说明 | 268| -------- | -------- | -------- | -------- | 269| id | [HiTraceId](#hitraceid) | 是 | 需要判断指定跟踪标志是否置位的HiTraceId实例。 | 270| flag | [HiTraceFlag](#hitraceflag) | 是 | 指定的跟踪标志。 | 271 272**返回值：** 273 274| 类型 | 说明 | 275| -------- | -------- | 276| boolean | 返回true标识HiTraceId已置位指定的flag，否则没有置位。 | 277 278**示例：** 279 280```js 281let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); 282// enabledDoNotCreateSpanFlag为true 283let enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(asyncTraceId, hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); 284``` 285 286## hiTraceChain.enableFlag 287 288enableFlag(id: HiTraceId, flag: HiTraceFlag): void 289 290置位HiTraceId对象中指定的跟踪标志，同步接口。 291 292**系统能力：** SystemCapability.HiviewDFX.HiTrace 293 294**参数：** 295 296| 参数名 | 类型 | 必填 | 说明 | 297| -------- | -------- | -------- | -------- | 298| id | [HiTraceId](#hitraceid) | 是 | 需要置位指定跟踪标志的HiTraceId实例。 | 299| flag | [HiTraceFlag](#hitraceflag) | 是 | 指定的跟踪标志。 | 300 301**示例：** 302 303```js 304let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); 305hiTraceChain.enableFlag(asyncTraceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 306// enabledDoNotCreateSpanFlag为true 307let enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(asyncTraceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 308``` 309