1# @ohos.hiTraceChain (Distributed Tracing) 2 3<!--Kit: Performance Analysis Kit--> 4<!--Subsystem: HiviewDFX--> 5<!--Owner: @qq_437963121--> 6<!--SE: @MontSaintMichel--> 7<!--TSE: @gcw_KuLfPSbe--> 8 9The **hiTraceChain** module implements call chain trace throughout a service process. It provides functions such as starting and stopping call chain trace and configuring trace points. 10 11> **NOTE** 12> 13> 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. 14 15## Modules to Import 16 17```ts 18import { hiTraceChain } from '@kit.PerformanceAnalysisKit'; 19``` 20 21## HiTraceFlag 22 23Enumerates trace flag types. 24 25**System capability**: SystemCapability.HiviewDFX.HiTrace 26 27| Name| Value| Description| 28| -------- | -------- | -------- | 29| DEFAULT | 0 | Default flag. | 30| 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. | 31| 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. | 32| 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. | 33| 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.| 34| DISABLE_LOG | 1 << 4 | Log association flag. If this flag is set, information about the trace task will not be printed. | 35| FAILURE_TRIGGER | 1 << 5 | Failure trigger flag. This flag is reserved for future use. | 36| 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.| 37 38## HiTraceTracepointType 39 40Enumerates trace point types. 41 42**System capability**: SystemCapability.HiviewDFX.HiTrace 43 44| Name| Value| Description| 45| -------- | -------- | -------- | 46| CS | 0 | CS trace point. | 47| CR | 1 | CR trace point. | 48| SS | 2 | SS trace point. | 49| SR | 3 | SR trace point. | 50| GENERAL | 4 | General trace points except CS, CR, SS, and SR.| 51 52## HiTraceCommunicationMode 53 54Enumerates communication modes. 55 56**System capability**: SystemCapability.HiviewDFX.HiTrace 57 58| Name| Value| Description| 59| -------- | -------- | -------- | 60| DEFAULT | 0 | Default communication. | 61| THREAD | 1 | Inter-thread communication. | 62| PROCESS | 2 | Inter-process communication. | 63| DEVICE | 3 | Inter-device communication. | 64 65## HiTraceId 66 67Defines a **HiTraceId** object. 68 69**System capability**: SystemCapability.HiviewDFX.HiTrace 70 71| Name| Type| Read-Only| Optional| Description| 72| -------- | -------- | -------- | -------- | -------- | 73| chainId | bigint | No| No| Call chain ID. | 74| spanId | number | No| Yes| Span ID. The default value is **0**. | 75| parentSpanId | number | No| Yes| Parent span ID. The default value is **0**. | 76| flags | number | No| Yes| Trace flag combination. The default value is **0**.| 77 78## hiTraceChain.begin 79 80begin(name: string, flags?: number): HiTraceId 81 82Starts call chain trace. This API returns the result synchronously. 83 84**System capability**: SystemCapability.HiviewDFX.HiTrace 85 86**Parameters** 87 88| Name| Type| Mandatory| Description| 89| -------- | -------- | -------- | -------- | 90| name | string | Yes| Traced service name.| 91| flags | number | No| Trace flag combination. For details, see [HiTraceFlag](#hitraceflag). The default value is **0**.| 92 93**Return value** 94 95| Type| Description| 96| -------- | -------- | 97| [HiTraceId](#hitraceid) | **HiTraceId** instance.| 98 99**Example** 100 101```ts 102// Start call chain trace. The trace flag is the union of INCLUDE_ASYNC and DONOT_CREATE_SPAN. 103let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 104// End the call chain trace after the service logic is executed for several times. 105hiTraceChain.end(traceId); 106``` 107 108## hiTraceChain.end 109 110end(id: HiTraceId): void 111 112Stops call chain trace. This API works in synchronous manner. 113 114**System capability**: SystemCapability.HiviewDFX.HiTrace 115 116**Parameters** 117 118| Name| Type| Mandatory| Description| 119| -------- | -------- | -------- | -------- | 120| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| 121 122**Example** 123 124```ts 125// Enable call chain trace. The trace flag is DEFAULT. 126let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 127// End the call chain trace after the service logic is executed for several times. 128hiTraceChain.end(traceId); 129``` 130 131## hiTraceChain.getId 132 133getId(): HiTraceId 134 135Obtains the trace ID. This API returns the result synchronously. 136 137**System capability**: SystemCapability.HiviewDFX.HiTrace 138 139**Return value** 140 141| Type| Description| 142| -------- | -------- | 143| [HiTraceId](#hitraceid) | **HiTraceId** instance.| 144 145**Example** 146 147```ts 148// Enable call chain trace. The trace flag is DEFAULT. 149let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 150// After the service logic is executed for several times, obtain the current trace ID. 151let curTraceId = hiTraceChain.getId(); 152// The call chain IDs in the trace IDs obtained from the same call chain trace must be the same. 153if (curTraceId.chainId != traceId.chainId) { 154// Processing logic for exceptions. 155} 156// End the call chain trace after the service logic is executed for several times. 157hiTraceChain.end(traceId); 158``` 159 160## hiTraceChain.setId 161 162setId(id: HiTraceId): void 163 164Sets a trace ID. This API returns the result synchronously. 165 166**System capability**: SystemCapability.HiviewDFX.HiTrace 167 168**Parameters** 169 170| Name| Type| Mandatory| Description| 171| -------- | -------- | -------- | -------- | 172| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| 173 174**Example** 175 176```ts 177// Obtain the trace ID of the current call chain. 178let traceId = hiTraceChain.getId(); 179// Set traceId to the obtained trace ID. 180hiTraceChain.setId(traceId); 181``` 182 183## hiTraceChain.clearId 184 185clearId(): void 186 187Clears the trace ID. This API returns the result synchronously. 188 189**System capability**: SystemCapability.HiviewDFX.HiTrace 190 191**Example** 192 193```ts 194// Before the service starts, try to clear the trace ID. 195hiTraceChain.clearId(); 196// Enable call chain trace. The trace flag is DEFAULT. 197let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 198// End the call chain trace after the service logic is executed for several times. 199hiTraceChain.end(traceId); 200``` 201 202## hiTraceChain.createSpan 203 204createSpan(): HiTraceId 205 206Creates a trace span. This API works in synchronous manner. 207 208**System capability**: SystemCapability.HiviewDFX.HiTrace 209 210**Return value** 211 212| Type| Description| 213| -------- | -------- | 214| [HiTraceId](#hitraceid) | **HiTraceId** instance.| 215 216**Example** 217 218```ts 219// Enable call chain trace. The trace flag is DEFAULT. 220let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 221// Create a trace span after the service logic is executed for several times. 222let spanTraceId = hiTraceChain.createSpan(); 223// The call chain IDs in the trace IDs obtained from the same call chain trace must be the same. 224if (spanTraceId.chainId != traceId.chainId) { 225// Processing logic for exceptions. 226} 227// The service is complete. Disable call chain trace. 228hiTraceChain.end(traceId); 229``` 230 231## hiTraceChain.tracepoint 232 233tracepoint(mode: HiTraceCommunicationMode, type: HiTraceTracepointType, id: HiTraceId, msg?: string): void 234 235Triggers a trace point. This API returns the result synchronously. 236 237**System capability**: SystemCapability.HiviewDFX.HiTrace 238 239**Parameters** 240 241| Name| Type| Mandatory| Description| 242| -------- | -------- | -------- | -------- | 243| mode | [HiTraceCommunicationMode](#hitracecommunicationmode) | Yes| Communication mode for the trace point.| 244| type | [HiTraceTracepointType](#hitracetracepointtype)| Yes| Trace point type.| 245| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance for trace point triggering.| 246| msg | string | No| Trace description passed for trace point triggering.| 247 248**Example** 249 250```ts 251// Start call chain trace. The trace flag is the union of INCLUDE_ASYNC and DONOT_CREATE_SPAN. 252let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 253// Trigger the trace point after the service logic is executed for several times. 254hiTraceChain.tracepoint(hiTraceChain.HiTraceCommunicationMode.THREAD, hiTraceChain.HiTraceTracepointType.SS, traceId, "Just a example"); 255// The service is complete. Disable call chain trace. 256hiTraceChain.end(traceId); 257``` 258 259## hiTraceChain.isValid 260 261isValid(id: HiTraceId): boolean 262 263Checks whether a **HiTraceId** instance is valid. This API returns the result synchronously. 264 265**System capability**: SystemCapability.HiviewDFX.HiTrace 266 267**Parameters** 268 269| Name| Type| Mandatory| Description| 270| -------- | -------- | -------- | -------- | 271| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| 272 273**Return value** 274 275| Type| Description| 276| -------- | -------- | 277| boolean | Boolean value indicating whether the **HiTraceId** instance is valid. The value **true** means yes and the value **false** means no.| 278 279**Example** 280 281```ts 282// Enable call chain trace. The trace flag is DEFAULT. 283let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.DEFAULT); 284// Set the value of traceIdIsvalid to true. 285let traceIdIsvalid = hiTraceChain.isValid(traceId); 286if (traceIdIsvalid) { 287// Processing logic for the scenario where the validity check on the trace ID is successful. 288} 289// The service is complete. Disable call chain trace. 290hiTraceChain.end(traceId); 291``` 292 293## hiTraceChain.isFlagEnabled 294 295isFlagEnabled(id: HiTraceId, flag: HiTraceFlag): boolean 296 297Checks whether the specified trace flag in the **HiTraceId** instance is enabled. This API returns the result synchronously. 298 299**System capability**: SystemCapability.HiviewDFX.HiTrace 300 301**Parameters** 302 303| Name| Type| Mandatory| Description| 304| -------- | -------- | -------- | -------- | 305| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| 306| flag | [HiTraceFlag](#hitraceflag) | Yes| Specified trace flag.| 307 308**Return value** 309 310| Type| Description| 311| -------- | -------- | 312| 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.| 313 314**Example** 315 316```ts 317// Enable call chain trace. The trace flag is INCLUDE_ASYNC. 318let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); 319// Set the value of enabledIncludeAsyncFlag to true. 320let enabledIncludeAsyncFlag = hiTraceChain.isFlagEnabled(traceId, hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); 321if (enabledIncludeAsyncFlag) { 322// Processing logic for the scenario where the INCLUDE_ASYNC trace flag has been set. 323} 324// The service is complete. Disable call chain trace. 325hiTraceChain.end(traceId); 326``` 327 328## hiTraceChain.enableFlag 329 330enableFlag(id: HiTraceId, flag: HiTraceFlag): void 331 332Enables the specified trace flag in the **HiTraceId** instance. This API returns the result synchronously. 333 334**System capability**: SystemCapability.HiviewDFX.HiTrace 335 336**Parameters** 337 338| Name| Type| Mandatory| Description| 339| -------- | -------- | -------- | -------- | 340| id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| 341| flag | [HiTraceFlag](#hitraceflag) | Yes| Specified trace flag.| 342 343**Example** 344 345```ts 346// Enable call chain trace. The trace flag is INCLUDE_ASYNC. 347let traceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); 348// Set the value of enabledDoNotCreateSpanFlag to false. 349let enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(traceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 350// Set the DONOT_CREATE_SPAN trace flag. 351hiTraceChain.enableFlag(traceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 352// Set the value of enabledDoNotCreateSpanFlag to true. 353enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(traceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); 354if (enabledDoNotCreateSpanFlag) { 355// Processing logic for the scenario where the DONOT_CREATE_SPAN trace flag has been set. 356} 357// The service is complete. Disable call chain trace. 358hiTraceChain.end(traceId); 359``` 360