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