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 97// Start call chain trace. The trace flag is the union of INCLUDE_ASYNC and DONOT_CREATE_SPAN. 98let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 99// End the call chain tracing after the service logic is executed for several times. 100hiTraceChain.end(traceId); 101``` 102 103## hiTraceChain.end 104 105end(id: HiTraceId): void 106 107Stops call chain tracing. This API works in synchronous manner. 108 109**System capability**: SystemCapability.HiviewDFX.HiTrace 110 111**Parameters** 112 113| Name| Type| Mandatory| Description| 114| -------- | -------- | -------- | -------- | 115| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| 116 117**Example** 118 119```ts 120// Enable call chain trace. The trace flag is DEFAULT. 121let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 122// End the call chain tracing after the service logic is executed for several times. 123hiTraceChain.end(traceId); 124``` 125 126## hiTraceChain.getId 127 128getId(): HiTraceId 129 130Obtains the trace ID. This API returns the result synchronously. 131 132**System capability**: SystemCapability.HiviewDFX.HiTrace 133 134**Return value** 135 136| Type| Description| 137| -------- | -------- | 138| [HiTraceId](#hitraceid) | **HiTraceId** instance.| 139 140**Example** 141 142```ts 143// Enable call chain trace. The trace flag is DEFAULT. 144let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 145// After the service logic is executed for several times, obtain the current trace ID. 146let curTraceId = hiTraceChain.getId(); 147// The call chain IDs in the trace IDs obtained from the same call chain trace must be the same. 148if (curTraceId.chainId != traceId.chainId) { 149// Processing logic for exceptions. 150} 151// End the call chain tracing after the service logic is executed for several times. 152hiTraceChain.end(traceId); 153``` 154 155## hiTraceChain.setId 156 157setId(id: HiTraceId): void 158 159Sets a trace ID. This API returns the result synchronously. 160 161**System capability**: SystemCapability.HiviewDFX.HiTrace 162 163**Parameters** 164 165| Name| Type| Mandatory| Description| 166| -------- | -------- | -------- | -------- | 167| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| 168 169**Example** 170 171```ts 172// Obtain the trace ID of the current call chain. 173let traceId = hiTraceChain.getId(); 174// Set traceId to the obtained trace ID. 175hiTraceChain.setId(traceId); 176``` 177 178## hiTraceChain.clearId 179 180clearId(): void 181 182Clears the trace ID. This API returns the result synchronously. 183 184**System capability**: SystemCapability.HiviewDFX.HiTrace 185 186**Example** 187 188```ts 189// Before the service starts, try to clear the trace ID. 190hiTraceChain.clearId(); 191// Enable call chain trace. The trace flag is DEFAULT. 192let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 193// End the call chain tracing after the service logic is executed for several times. 194hiTraceChain.end(traceId); 195``` 196 197## hiTraceChain.createSpan 198 199createSpan(): HiTraceId 200 201Creates a trace span. This API works in synchronous manner. 202 203**System capability**: SystemCapability.HiviewDFX.HiTrace 204 205**Return value** 206 207| Type| Description| 208| -------- | -------- | 209| [HiTraceId](#hitraceid) | **HiTraceId** instance.| 210 211**Example** 212 213```ts 214// Enable call chain trace. The trace flag is DEFAULT. 215let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 216// Create a trace span after the service logic is executed for several times. 217let spanTraceId = hiTraceChain.createSpan(); 218// The call chain IDs in the trace IDs obtained from the same call chain trace must be the same. 219if (spanTraceId.chainId != traceId.chainId) { 220// Processing logic for exceptions. 221} 222// The service is complete. Disable call chain trace. 223hiTraceChain.end(traceId); 224``` 225 226## hiTraceChain.tracepoint 227 228tracepoint(mode: HiTraceCommunicationMode, type: HiTraceTracepointType, id: HiTraceId, msg?: string): void 229 230Triggers a trace point. This API returns the result synchronously. 231 232**System capability**: SystemCapability.HiviewDFX.HiTrace 233 234**Parameters** 235 236| Name| Type| Mandatory| Description| 237| -------- | -------- | -------- | -------- | 238| mode | [HiTraceCommunicationMode](#hitracecommunicationmode) | Yes| Communication mode for the trace point.| 239| type | [HiTraceTracepointType](#hitracetracepointtype)| Yes| Trace point type.| 240| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance for trace point triggering.| 241| msg | string | No| Trace description passed for trace point triggering.| 242 243**Example** 244 245```ts 246// Start call chain trace. The trace flag is the union of INCLUDE_ASYNC and DONOT_CREATE_SPAN. 247let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 248// Trigger the trace point after the service logic is executed for several times. 249hiTraceChain.tracepoint(hiTraceChain.HiTraceCommunicationMode.THREAD, hiTraceChain.HiTraceTracepointType.SS, traceId, "Just a example"); 250// The service is complete. Disable call chain trace. 251hiTraceChain.end(traceId); 252``` 253 254## hiTraceChain.isValid 255 256isValid(id: HiTraceId): boolean 257 258Checks whether a **HiTraceId** instance is valid. This API returns the result synchronously. 259 260**System capability**: SystemCapability.HiviewDFX.HiTrace 261 262**Parameters** 263 264| Name| Type| Mandatory| Description| 265| -------- | -------- | -------- | -------- | 266| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| 267 268**Return value** 269 270| Type| Description| 271| -------- | -------- | 272| boolean | Boolean value indicating whether the **HiTraceId** instance is valid. The value **true** means yes and the value **false** means no.| 273 274**Example** 275 276```ts 277// Enable call chain trace. The trace flag is DEFAULT. 278let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 279// Set the value of traceIdIsvalid to true. 280let traceIdIsvalid = hiTraceChain.isValid(traceId); 281if (traceIdIsvalid) { 282// Processing logic for the scenario where the validity check on the trace ID is successful. 283} 284// The service is complete. Disable call chain trace. 285hiTraceChain.end(traceId); 286``` 287 288## hiTraceChain.isFlagEnabled 289 290isFlagEnabled(id: HiTraceId, flag: HiTraceFlag): boolean 291 292Checks whether the specified trace flag in the **HiTraceId** instance is enabled. This API returns the result synchronously. 293 294**System capability**: SystemCapability.HiviewDFX.HiTrace 295 296**Parameters** 297 298| Name| Type| Mandatory| Description| 299| -------- | -------- | -------- | -------- | 300| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| 301| flag | [HiTraceFlag](#hitraceflag) | Yes| Specified trace flag.| 302 303**Return value** 304 305| Type| Description| 306| -------- | -------- | 307| 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.| 308 309**Example** 310 311```ts 312// Enable call chain trace. The trace flag is INCLUDE_ASYNC. 313let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); 314// Set the value of enabledIncludeAsyncFlag to true. 315let enabledIncludeAsyncFlag = hiTraceChain.isFlagEnabled(traceId, hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); 316if (enabledIncludeAsyncFlag) { 317// Processing logic for the scenario where the INCLUDE_ASYNC trace flag has been set. 318} 319// The service is complete. Disable call chain trace. 320hiTraceChain.end(traceId); 321``` 322 323## hiTraceChain.enableFlag 324 325enableFlag(id: HiTraceId, flag: HiTraceFlag): void 326 327Enables the specified trace flag in the **HiTraceId** instance. This API returns the result synchronously. 328 329**System capability**: SystemCapability.HiviewDFX.HiTrace 330 331**Parameters** 332 333| Name| Type| Mandatory| Description| 334| -------- | -------- | -------- | -------- | 335| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| 336| flag | [HiTraceFlag](#hitraceflag) | Yes| Specified trace flag.| 337 338**Example** 339 340```ts 341// Enable call chain trace. The trace flag is INCLUDE_ASYNC. 342let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); 343// Set the value of enabledDoNotCreateSpanFlag to false. 344let enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(traceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 345// Set the DONOT_CREATE_SPAN trace flag. 346hiTraceChain.enableFlag(traceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 347// Set the value of enabledDoNotCreateSpanFlag to true. 348enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(traceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 349if (enabledDoNotCreateSpanFlag) { 350// Processing logic for the scenario where the DONOT_CREATE_SPAN trace flag has been set. 351} 352// The service is complete. Disable call chain trace. 353hiTraceChain.end(traceId); 354``` 355