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