1# @ohos.hiTraceChain (Distributed Tracing) 2 3The **hiTraceChain** module implements call chain tracing throughout a service process. It provides functions such as starting and stopping call chain tracing and configuring trace points. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```ts 12import hiTraceChain from '@ohos.hiTraceChain'; 13``` 14 15 16## HiTraceFlag 17 18Enumerates trace flag types. 19 20**System capability**: SystemCapability.HiviewDFX.HiTrace 21 22| Name| Value| Description| 23| -------- | -------- | -------- | 24| DEFAULT | 0 | Default flag. | 25| INCLUDE_ASYNC | 1 | Asynchronous call flag. By default, only synchronous calls are traced. If this flag is set, both synchronous and asynchronous calls will be traced. | 26| DONOT_CREATE_SPAN | 1 << 1 | No span flag. By default, spans are created within a trace of synchronous and asynchronous service calls. If this flag is set, no spans are created. | 27| TP_INFO | 1 << 2 | Trace point flag. By default, no trace point is added when trace is enabled. This flag is used for debugging. If this flag is set, trace points will be automatically added on the TX and RX sides of synchronous and asynchronous calls to output trace point and timestamp information. Trace points are classified into four types: [CS, SR, SS, and CR](#hitracetracepointtype). For a synchronous call, the output trace points are CS, SR, SS, and CR; for an asynchronous call, the output trace points are CS, SR, and SS. | 28| NO_BE_INFO | 1 << 3 | No begin/end flag. By default, information about the start and end of the trace task is printed. If this flag is set, information about the start and end of the trace task will not be printed.| 29| DISABLE_LOG | 1 << 4 | Log association flag. If this flag is set, information about the trace task will not be printed. | 30| FAILURE_TRIGGER | 1 << 5 | Failure trigger flag. This flag is reserved for future use. | 31| D2D_TP_INFO | 1 << 6 | Device-to-device trace point flag. It is a subset of **TP_INFO**. If this flag is set, trace points are added only for call chain trace between devices.| 32 33## HiTraceTracepointType 34 35Enumerates trace point types. 36 37**System capability**: SystemCapability.HiviewDFX.HiTrace 38 39| Name| Value| Description| 40| -------- | -------- | -------- | 41| CS | 0 | CS trace point. | 42| CR | 1 | CR trace point. | 43| SS | 2 | SS trace point. | 44| SR | 3 | SR trace point. | 45| GENERAL | 4 | General trace points except CS, CR, SS, and SR.| 46 47## HiTraceCommunicationMode 48 49Enumerates communication modes. 50 51**System capability**: SystemCapability.HiviewDFX.HiTrace 52 53| Name| Value| Description| 54| -------- | -------- | -------- | 55| DEFAULT | 0 | Default communication mode. | 56| THREAD | 1 | Inter-thread communication. | 57| PROCESS | 2 | Inter-process communication. | 58| DEVICE | 3 | Inter-device communication. | 59 60## HiTraceId 61 62Defines a **HiTraceId** object. 63 64**System capability**: SystemCapability.HiviewDFX.HiTrace 65 66| Name| Type| Mandatory| Description| 67| -------- | -------- | -------- | -------- | 68| chainId | bigint | Yes| Call chain ID. | 69| spanId | number | No| Span ID. | 70| parentSpanId | number | No| Parent span ID. | 71| flags | number | No| Trace flag combination.| 72 73## hiTraceChain.begin 74 75begin(name: string, flags?: number): HiTraceId 76 77Starts call chain tracing. This API returns the result synchronously. 78 79**System capability**: SystemCapability.HiviewDFX.HiTrace 80 81**Parameters** 82 83| Name| Type| Mandatory| Description| 84| -------- | -------- | -------- | -------- | 85| name | string | Yes| Traced service name.| 86| flags | number | No| Trace flag combination. For details, see [HiTraceFlag](#hitraceflag).| 87 88**Return value** 89 90| Type| Description| 91| -------- | -------- | 92| [HiTraceId](#hitraceid) | **HiTraceId** instance.| 93 94**Example** 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 104Stops call chain tracing. This API works in synchronous manner. 105 106**System capability**: SystemCapability.HiviewDFX.HiTrace 107 108**Parameters** 109 110| Name| Type| Mandatory| Description| 111| -------- | -------- | -------- | -------- | 112| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| 113 114**Example** 115 116```ts 117let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 118// End the call chain tracing after the service logic is executed for several times. 119hiTraceChain.end(asyncTraceId); 120``` 121 122## hiTraceChain.getId 123 124getId(): HiTraceId 125 126Obtains the trace ID. This API returns the result synchronously. 127 128**System capability**: SystemCapability.HiviewDFX.HiTrace 129 130**Return value** 131 132| Type| Description| 133| -------- | -------- | 134| [HiTraceId](#hitraceid) | **HiTraceId** instance.| 135 136**Example** 137 138```ts 139let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 140// Obtain the current trace ID after the service logic is executed for several times. 141let curTraceId = hiTraceChain.getId(); 142``` 143 144## hiTraceChain.setId 145 146setId(id: HiTraceId): void 147 148Sets a trace ID. This API returns the result synchronously. 149 150**System capability**: SystemCapability.HiviewDFX.HiTrace 151 152**Parameters** 153 154| Name| Type| Mandatory| Description| 155| -------- | -------- | -------- | -------- | 156| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| 157 158**Example** 159 160```ts 161let asyncTraceId: hiTraceChain.HiTraceId; 162hiTraceChain.end(asyncTraceId); 163let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 164// Set the previous trace ID to the current trace ID after the service logic is executed for several times. 165hiTraceChain.setId(asyncTraceId); 166``` 167 168## hiTraceChain.clearId 169 170clearId(): void 171 172Clears the trace ID. This API returns the result synchronously. 173 174**System capability**: SystemCapability.HiviewDFX.HiTrace 175 176**Example** 177 178```ts 179let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 180// Clear the current trace ID after the service logic is executed for several times. 181hiTraceChain.clearId(); 182``` 183 184## hiTraceChain.createSpan 185 186createSpan(): HiTraceId 187 188Creates a trace span. This API works in synchronous manner. 189 190**System capability**: SystemCapability.HiviewDFX.HiTrace 191 192**Return value** 193 194| Type| Description| 195| -------- | -------- | 196| [HiTraceId](#hitraceid) | **HiTraceId** instance.| 197 198**Example** 199 200```ts 201let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 202// Create a trace span after the service logic is executed for several times. 203let spanTraceId = hiTraceChain.createSpan(); 204``` 205 206## hiTraceChain.tracepoint 207 208tracepoint(mode: HiTraceCommunicationMode, type: HiTraceTracepointType, id: HiTraceId, msg?: string): void 209 210Triggers a trace point. This API returns the result synchronously. 211 212**System capability**: SystemCapability.HiviewDFX.HiTrace 213 214**Parameters** 215 216| Name| Type| Mandatory| Description| 217| -------- | -------- | -------- | -------- | 218| mode | [HiTraceCommunicationMode](#hitracecommunicationmode) | Yes| Communication mode for the trace point.| 219| type | [HiTraceTracepointType](#hitracetracepointtype)| Yes| Trace point type.| 220| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance for trace point triggering.| 221| msg | string | No| Trace description passed for trace point triggering.| 222 223**Example** 224 225```ts 226let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 227// Trigger the trace point after the service logic is executed for several times. 228hiTraceChain.tracepoint(hiTraceChain.HiTraceCommunicationMode.THREAD, hiTraceChain.HiTraceTracepointType.SS, asyncTraceId, "Just a example"); 229``` 230 231## hiTraceChain.isValid 232 233isValid(id: HiTraceId): boolean 234 235Checks whether a **HiTraceId** instance is valid. This API returns the result synchronously. 236 237**System capability**: SystemCapability.HiviewDFX.HiTrace 238 239**Parameters** 240 241| Name| Type| Mandatory| Description| 242| -------- | -------- | -------- | -------- | 243| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| 244 245**Return value** 246 247| Type| Description| 248| -------- | -------- | 249| boolean | Boolean value indicating whether the **HiTraceId** instance is valid. The value **true** means yes and the value **false** means no.| 250 251**Example** 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 262Checks whether the specified trace flag in the **HiTraceId** instance is enabled. This API returns the result synchronously. 263 264**System capability**: SystemCapability.HiviewDFX.HiTrace 265 266**Parameters** 267 268| Name| Type| Mandatory| Description| 269| -------- | -------- | -------- | -------- | 270| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| 271| flag | [HiTraceFlag](#hitraceflag) | Yes| Specified trace flag.| 272 273**Return value** 274 275| Type| Description| 276| -------- | -------- | 277| boolean | Boolean value indicating whether the specified trace flag in the **HiTraceId** instance is enabled. The value **true** means yes and the value **false** means no.| 278 279**Example** 280 281```ts 282let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); 283// The value of enabledDoNotCreateSpanFlag is true. 284let enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(asyncTraceId, hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); 285``` 286 287## hiTraceChain.enableFlag 288 289enableFlag(id: HiTraceId, flag: HiTraceFlag): void 290 291Enables the specified trace flag in the **HiTraceId** instance. This API returns the result synchronously. 292 293**System capability**: SystemCapability.HiviewDFX.HiTrace 294 295**Parameters** 296 297| Name| Type| Mandatory| Description| 298| -------- | -------- | -------- | -------- | 299| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| 300| flag | [HiTraceFlag](#hitraceflag) | Yes| Specified trace flag.| 301 302**Example** 303 304```ts 305let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); 306hiTraceChain.enableFlag(asyncTraceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 307// The value of enabledDoNotCreateSpanFlag is true. 308let enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(asyncTraceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 309``` 310