1# Using HiTraceChain (ArkTS/JS)
2
3## Overview
4
5hiTraceChain is a lightweight implementation of the cloud-based distributed call chain tracing on the device side. It allows the calls made in a service process to be traced, helping locating issues across threads, processes, and devices. With hiTraceChain, a unique ID is generated for a service process, passed throughout the service process, and associated with various output information (including application events, system time, and logs). During debugging and fault locating, you can use this unique ID to quickly correlate various information related to the service process. hiTraceChain provides APIs to implement call chain tracing throughout a service process. This can help you quickly obtain the run log for the call chain of a service process and locate faults across devices, processes, and threads.
6
7## Basic Concepts
8
9**chainId**: a distributed trace ID that uniquely identifies a service process being traced. It is a part of **hiTraceId**.
10
11## Available APIs
12
13The APIs for distributed call chain tracing are provided by the **hiTraceChain** module. For details, see [Distributed Tracing](../reference/apis-performance-analysis-kit/js-apis-hitracechain.md).
14
15**APIs for distributed call chain tracing**
16
17| API                                                                  | Description        |
18| ------------------------------------------------------------------------|------------ |
19| hiTraceChain.begin(name: string, flags?: number = HiTraceFlag.DEFAULT)   |Starts call chain tracing.  |
20| hiTraceChain.end(id: HiTraceId)                                          |Stops call chain tracing.   |
21
22## How to Develop
23
24The following example walks you through on how to implement distributed call chain tracing on  a one-time [application event logging](../reference/apis-performance-analysis-kit/js-apis-hiviewdfx-hiappevent.md).
25
261. Create an ets application project. In the **entry/src/main/ets/pages/index.ets** file, add a button to trigger system event logging. The sample code is as follows:
27
28    ```ts
29    import { BusinessError } from '@kit.BasicServicesKit';
30    import { hiAppEvent, hilog, hiTraceChain } from '@kit.PerformanceAnalysisKit';
31
32    @Entry
33    @Component
34    struct Index {
35      @State message: string = 'Start writing an app event'
36
37      build() {
38        Row() {
39          Column() {
40            Button(this.message)
41              .fontSize(20)
42              .margin(5)
43              .width(350)
44              .height(60)
45              .fontWeight(FontWeight.Bold)
46              .onClick(() => {
47                try {
48                  // Start distributed call chain tracing before the service starts.
49                  let traceId = hiTraceChain.begin("Write a new app event", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC)
50                  // Log a button onclick event when the button is clicked.
51                  let eventParams: Record<string, number> = { 'click_time': 100 }
52                  let eventInfo: hiAppEvent.AppEventInfo = {
53                    // Define the event domain.
54                    domain: "button",
55                    // Define the event name.
56                    name: "click",
57                    // Define the event type.
58                    eventType: hiAppEvent.EventType.BEHAVIOR,
59                    // Define the event parameters.
60                    params: eventParams,
61                  }
62                  hiAppEvent.write(eventInfo).then(() => {
63                    hilog.info(0x0000, 'testTag', `Succeed to write an app event`)
64                    // Stop distributed call chain tracing when the service ends.
65                    hiTraceChain.end(traceId)
66                  }).catch((err: BusinessError) => {
67                    hilog.error(0x0000, 'testTag', `HiAppEvent err.code: ${err.code}, err.message: ${err.message}`)
68                  })
69                } catch (err) {
70                  console.error(`error message is ${(err as BusinessError).message}`)
71                }
72              })
73          }
74          .width('100%')
75        }
76        .height('100%')
77      }
78    }
79    ```
80
812. In DevEco Studio, click the **Run** button to run the project. Then, click the **Start writing an app event** button on the application UI to trigger system event logging.
82
833. View the information printed in the **Log** window. <br>You can use **.*\[([0-9a-zA-Z]{15}).*].** to filter log information and view the distributed call chain tracing information specific to the service. <br>The process ID of the HAP service is **21519**. Two threads, whose IDs are **21519** and **23924**, are involved in the system event logging. Based on the chain ID **a92ab94c18e1341**, you can trace the log information of the two threads.
84    ```text
85    11-02 15:13:28.922  21519-21519  C02D03/HiTraceC                  com.example.hitracechaintest     I  [a92ab94c18e1341 0 0][dict]HiTraceBegin name:Write a new app event flags:0x01.
86    11-02 15:13:28.924  21519-21519  C03915/AceInputTracking          com.example.hitracechaintest     I  [a92ab94c18e1341 0 0][ace_view_ohos.cpp(operator())-(0)] touch Event markProcessed in ace_view, eventInfo: id:764
87    11-02 15:13:28.926  21519-23924  C02D07/HiAppEvent_ObserverMgr    com.example.hitracechaintest     I  [a92ab94c18e1341 0 0]start to handle event
88    11-02 15:13:28.930  21519-21519  A00000/testTag                   com.example.hitracechaintest     I  [a92ab94c18e1341 324c3a3 0]Succeed to write an app event
89    11-02 15:13:28.930  21519-21519  C02D03/HiTraceC                  com.example.hitracechaintest     I  [a92ab94c18e1341 324c3a3 0][dict]HiTraceEnd.
90   ```
91
92## Constraints
93
94The distributed call chain tracing across processes or devices depends on whether inter-process or inter-device communication exists in the Node-API implementations of  OpenHarmony modules<!--Del-->. For details, see <!--Del-->[HiTraceChain Development Guide](../../device-dev/subsystems/subsys-dfx-hitracechain.md)<!--DelEnd-->.
95