1# Development of Distributed Call Chain Tracing 2 3## Overview 4 5hiTraceChain is a lightweight implementation of the cloud-based distributed call chain tracing. It allows applications to trace cross-thread, cross-process, and cross-device service calls. The hiTraceChain module generates a unique **chainId** for a service process and passes it to various information (including application events, system time, and logs) specific to the service process. During debugging and fault locating, you can use the unique **chainId** to quickly correlate various information related to the service process. The hiTraceChain module 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 specified service process and locate faults in inter-device, inter-process, or inter-thread communications. 6 7## Basic Concepts 8 9- **chainId** 10 11 Distributed call chain tracing ID, which is a part of **HiTraceId** and is used to identify the service process being traced. 12 13## Available APIs 14 15The APIs for distributed call chain tracing are provided by the **hiTraceChain** module. For details, see [API Reference](../reference/apis/js-apis-hitracechain.md). 16 17**APIs for distributed call chain tracing** 18 19| API | Return Value | Description | 20| ------------------------------------------------------------------------------------------------------------------- | -------------- | ------------ | 21| hiTraceChain.begin(name: string, flags?: number = HiTraceFlag.DEFAULT) | HiTraceId | Starts call chain tracing. | 22| hiTraceChain.end(id: HiTraceId) | void | Stops call chain tracing. | 23 24## How to Develop 25 26The following example illustrates how to simulate one-time [system event logging](../reference/apis/js-apis-hiviewdfx-hiappevent.md) to implement distributed call chain tracing. 27 281. Create an eTS application project. In the displayed **Project** window, choose **entry** > **src** > **main** > **ets** > **pages** > **index.ets**, and double-click **index.ets**. Then, add a button to trigger system event logging. 29 30 ```ts 31 import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent' 32 import hilog from '@ohos.hilog' 33 import hiTraceChain from '@ohos.hiTraceChain' 34 import { BusinessError } from '@ohos.base' 35 36 @Entry 37 @Component 38 struct Index { 39 @State message: string = 'Start writing an app event' 40 41 build() { 42 Row() { 43 Column() { 44 Button(this.message) 45 .fontSize(20) 46 .margin(5) 47 .width(350) 48 .height(60) 49 .fontWeight(FontWeight.Bold) 50 .onClick(() => { 51 try { 52 // Enable distributed call chain tracing before the service starts. 53 let traceId = hiTraceChain.begin("Write a new app event", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC) 54 // Enable event logging in the button click function to log button click events. 55 let eventParams: Record<string, number> = { 'click_time': 100 } 56 let eventInfo: hiAppEvent.AppEventInfo = { 57 // Define the event domain. 58 domain: "button", 59 // Define the event name. 60 name: "click", 61 // Define the event type. 62 eventType: hiAppEvent.EventType.BEHAVIOR, 63 // Define event parameters. 64 params: eventParams, 65 } 66 hiAppEvent.write(eventInfo).then(() => { 67 hilog.info(0x0000, 'testTag', `Succeed to write an app event`) 68 // Disable distributed call chain tracing when the service ends. 69 hiTraceChain.end(traceId) 70 }).catch((err: BusinessError) => { 71 hilog.error(0x0000, 'testTag', `HiAppEvent err.code: ${err.code}, err.message: ${err.message}`) 72 }) 73 } catch (err) { 74 console.error(`error message is ${(err as BusinessError).message}`) 75 } 76 }) 77 } 78 .width('100%') 79 } 80 .height('100%') 81 } 82 } 83 ``` 84 852. Touch the run button on the IDE to run the project. Then, touch the **Start writing an app event** button on the application UI to trigger system event logging. 86 873. View the information printed in the **Log** window. You can use **.*\[([0-9a-zA-Z]{15}).*].*** to access distributed call chain tracing information specific to the service. The process ID of the 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 then effectively trace the log information of the two threads. 88 ```text 89 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. 90 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 91 11-02 15:13:28.926 21519-23924 C02D07/HiAppEvent_ObserverMgr com.example.hitracechaintest I [a92ab94c18e1341 0 0]start to handle event 92 11-02 15:13:28.930 21519-21519 A00000/testTag com.example.hitracechaintest I [a92ab94c18e1341 324c3a3 0]Succeed to write an app event 93 11-02 15:13:28.930 21519-21519 C02D03/HiTraceC com.example.hitracechaintest I [a92ab94c18e1341 324c3a3 0][dict]HiTraceEnd. 94 ``` 95 96## About Cross-Process/Cross-Device Distributed Call Chain Tracing 97 98Cross-process/cross-device distributed call chain tracing depends on the NAPI implementation of the corresponding service APIs of each OpenHarmony module. For details, see the [HiTraceChain Development](../../device-dev/subsystems/subsys-dfx-hitracechain.md). 99