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