1# HiTraceChain Development 2 3## Overview 4 5HiTraceChain tracks the call chain with the same **traceid** throughout the inter-device, inter-process, and inter-thread service processes. It associates and displays the call relationship and various output information during the entire process, helping you analyze and locate faults and optimize the system. 6 7 8## When to Use 9 10HiTraceChain can be used for the following purposes: 11 12- Associates and reports service process information (such as logs and events) on the device. 13 14- Displays and analyzes reported information on the cloud to facilitate fault location. 15 16- Works with the IDE to debug the detailed service process and time consumption distribution for system optimization. 17 18 **Figure 1** Use cases of HiTraceChain 19 20  21 22 23### Usage Example 24 25 **Figure 2** Service calling process \(inter-device and inter-process synchronous call\) 26 27 .png "service-calling-process-(inter-device-and-inter-process-synchronous-call)") 28 291. Display the call relationship in the service process, analyze key paths and function dependency, and determine the time consumption and call frequency at each call point to detect performance bottlenecks. 30 31 **Figure 3** Service calling process 32 33  34 35 36 **Figure 4** Time delay in the service calling process 37 38  39 402. Add **traceid** to logs and events automatically to facilitate comprehensive analysis and quick fault location. 41 42 43## Available APIs 44 45HiTraceChain provides C++ and C APIs. The upper-layer services mainly use HiTraceChain to start and stop call chain trace. 46 47HiTraceChain is implemented at layer C. It works by transferring **traceid** throughout the service calling process. Before service processing, HiTrace sets **traceid** in the thread local storage (TLS) of the calling thread. During service processing, HiTrace obtains **traceid** from the contextual TLS of the calling thread and automatically adds it to the log and event information. After service processing is complete, HiTrace clears **traceid** from the TLS of the calling thread. 48 49 50### Java, C++, and C APIs 51 52 **Table 1** Description of C++ and C APIs 53 54| | **C++** | **C** | 55| -------- | -------- | -------- | 56| **Class**| **Function**| **Function**| 57| HiTraceChain | HiTraceId Begin(const std::string& name, int flags) | HiTraceIdStruct HiTraceChainBegin(const char* name, int flags) | 58| | void End(const HiTraceId& id) | void HiTraceChainEnd(const HiTraceIdStruct* pId) | 59| | HiTraceId GetId(); | HiTraceIdStruct HiTraceChainGetId() | 60| | void SetId(const HiTraceId& id) | void HiTraceChainSetId(const HiTraceIdStruct* pId) | 61| | void ClearId() | void HiTraceChainClearId() | 62| | HiTraceId CreateSpan() | HiTraceIdStruct HiTraceChainCreateSpan() | 63| | void Tracepoint(HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...) | void HiTraceChainTracepoint(HiTraceTracepointType type, const HiTraceIdStruct* pId, const char* fmt, ...) | 64| | void Tracepoint(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...) | void HiTraceChainTracepointEx(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceIdStruct* pId, const char* fmt, ...) | 65| HiTraceId | HiTraceId(); | void HiTraceChainInitId(HiTraceIdStruct* pId) | 66| | HiTraceId(const uint8_t* pIdArray, int len) | HiTraceIdStruct HiTraceChainBytesToId(const uint8_t* pIdArray, int len) | 67| | bool IsValid() | int HiTraceChainIsValid(const HiTraceIdStruct* pId) | 68| | bool IsFlagEnabled(HiTraceFlag flag) | int HiTraceChainIsFlagEnabled(const HiTraceIdStruct* pId, HiTraceFlag flag) | 69| | void EnableFlag(HiTraceFlag flag) | void HiTraceChainEnableFlag(HiTraceIdStruct* pId, HiTraceFlag flag) | 70| | int GetFlags() | int HiTraceChainGetFlags(const HiTraceIdStruct* pId) | 71| | void SetFlags(int flags) | void HiTraceChainSetFlags(HiTraceIdStruct* pId, int flags) | 72| | uint64_t GetChainId() | uint64_t HiTraceChainGetChainId(const HiTraceIdStruct* pId) | 73| | void SetChainId(uint64_t chainId) | void HiTraceChainSetChainId(HiTraceIdStruct* pId, uint64_t chainId) | 74| | uint64_t GetSpanId() | uint64_t HiTraceChainGetSpanId(const HiTraceIdStruct* pId) | 75| | void SetSpanId(uint64_t spanId) | void HiTraceChainSetSpanId(HiTraceIdStruct* pId, uint64_t spanId) | 76| | uint64_t GetParentSpanId() | uint64_t HiTraceChainGetParentSpanId(const HiTraceIdStruct* pId) | 77| | void SetParentSpanId(uint64_t parentSpanId) | void HiTraceChainSetParentSpanId(HiTraceIdStruct* pId, uint64_t parentSpanId) | 78| | int ToBytes(uint8_t* pIdArray, int len) | int HiTraceChainIdToBytes(const HiTraceIdStruct_ pId, uint8_t* pIdArray, int len) | 79 80 81### Parameters of C++ APIs 82 83 **Table 2** Trace flag combination types 84 85| **Name**| **Value**| **Description**| 86| -------- | -------- | -------- | 87| HITRACE_FLAG_DEFAULT | 0 | Default flag. | 88| HITRACE_FLAG_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. | 89| HITRACE_FLAG_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. | 90| HITRACE_FLAG_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: client send (CS), server receive (SR), server send (SS), and client receive (CR). 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. | 91| HITRACE_FLAG_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.| 92| HITRACE_FLAG_DONOT_ENABLE_LOG | 1 << 4 | Log association flag. If this flag is set, information about the trace task will not be printed. | 93| HITRACE_FLAG_FAULT_TRIGGER | 1 << 5 | Failure trigger flag. This flag is reserved for future use. | 94| HITRACE_FLAG_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.| 95 96 **Table 3** Trace point types 97 98| **Name**| **Value**| **Description**| 99| -------- | -------- | -------- | 100| HITRACE_TP_CS | 0 | CS trace point. | 101| HITRACE_TP_CR | 1 | CR trace point. | 102| HITRACE_TP_SS | 2 | SS trace point. | 103| HITRACE_TP_SR | 3 | SR trace point. | 104| HITRACE_TP_GENERAL | 4 | General trace points except CS, CR, SS, and SR.| 105 106 **Table 4** Communication modes 107 108| **Name**| **Value**| **Description**| 109| -------- | -------- | -------- | 110| HITRACE_CM_DEFAULT | 0 | Default communication mode. | 111| HITRACE_CM_THREAD | 1 | Inter-thread communication. | 112| HITRACE_CM_PROCESS | 2 | Inter-process communication. | 113| HITRACE_CM_DEVICE | 3 | Inter-device communication. | 114 115 **Table 5** Description of C++ APIs 116 117| **Class**| **API**| **Description**| 118| -------- | -------- | -------- | 119| HiTraceChain | HiTraceId Begin(const std::string& name, int flags) | Starts HiTraceChain, generates a **HiTraceId** object, and sets it in the TLS of the calling thread.<br>Input arguments:<br>- **name**: name of the service process.<br>- **flags**: trace flags, which can be used in combination. For details, see Table 2.<br>Output arguments: none<br>Return value: a valid **HiTraceId** object if call chain trace is triggered successfully; returns an invalid object otherwise.<br>Note: In nested trace mode, an invalid object will be returned if trace is started at the nested layer.| 120| | void End(const HiTraceId& id) | Stops HiTraceChain based on the **HiTraceId** object returned by the **Begin** API, and clears the **HiTraceId** object in the TLS of the calling thread.<br>Input arguments:<br>- **id**: **HiTraceId** object.<br>Output arguments: none<br>Return value: none| 121| | HiTraceId GetId(); | Obtains the **HiTraceId** object from the TLS of the calling thread.<br>Input arguments: none<br>Output arguments: none<br>Return value: **HiTraceId** object in the contextual TLS of the calling thread.| 122| | void SetId(const HiTraceId& id) | Purpose: Sets the **HiTraceId** object in the TLS of the calling thread.<br>Input arguments:<br>- **id**: **HiTraceId** object.<br>Output arguments: none<br>Return value: none| 123| | void ClearId() | Clears the **HiTraceId** object in the TLS of the calling thread.<br>Input arguments: none<br>Output arguments: none<br>Return value: none| 124| | HiTraceId CreateSpan() | Obtains the span ID from the current **HiTraceId** object.<br>Input arguments: none<br>Output arguments: none<br>Return value: current span ID.| 125| | void Tracepoint(HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...) | Outputs HiTraceChain trace point information based on the information type. The information includes the timestamp and **HiTraceId** object of the span.<br>Input arguments:<br>- **type**: trace point type. For details, see Table 3.<br>- **id**: ID of the current span.<br>- **fmt**: string describing the format variable parameter.<br>- **args**: variable parameter.<br>Output arguments: none<br>Return value: none| 126| | void Tracepoint(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...) | Outputs HiTraceChain trace point information based on the communication mode and information type. The information includes the timestamp and **HiTraceId** object of the span.<br>Input arguments:<br>- **mode**: communication mode. For details, see Table 4.<br>- **type**: trace point type. For details, see Table 3.<br>- **id**: ID of the current span.<br>- **fmt**: string describing the format variable parameter.<br>- **args**: variable parameter.<br>Output arguments: none<br>Return value: none| 127| HiTraceId | HiTraceId(); | Represents the default constructor used to generate an invalid **HiTraceId** object. <br>Input arguments: none<br>Output arguments: none<br>Return value: none| 128| | HiTraceId(const uint8_t* pIdArray, int len) | Represents the constructor used to create a **HiTraceId** object based on the specified byte array. <br>Input arguments:<br>- **pIdArray**: pointer to a byte array.<br>- **len**: length of the byte array.<br>Output arguments: none<br>Return value: none| 129| | bool IsValid() | Checks whether the **HiTraceId** object is valid.<br>Input arguments: none<br>Output arguments: none<br>Return value: **true** if the **HiTraceId** object is valid; **false** otherwise.| 130| | bool IsFlagEnabled(HiTraceFlag flag) | Checks whether the trace flag of the **HiTraceId** object is enabled.<br>Input arguments:<br>- **flag**: trace flag. For details, see the description in the **Begin** function.<br>Output arguments: none<br>Return value: **true** if the trace flag is enabled; **false** otherwise.| 131| | void EnableFlag(HiTraceFlag flag) | Enables the trace flag of the **HiTraceId** object.<br>Input arguments:<br>- **flag**: trace flag. For details, see the description in the **Begin** function.<br>Output arguments: none<br>Return value: none| 132| | int GetFlags() | Obtains the trace flag set in the **HiTraceId** object.<br>Input arguments: none<br>Output arguments: none<br>Return value: Returns the combination of trace flags. For details, see the description in the **Begin** function.| 133| | void SetFlags(int flags) | Sets a trace flag in the **HiTraceId** object.<br>Input arguments:<br>- **flags**: combination of trace flags. For details, see the description in the **Begin** function.<br>Output arguments: none<br>Return value: none| 134| | uint64_t GetChainId() | Obtains the call chain ID.<br>Input arguments: none<br>Output arguments: none<br>Return value: call chain ID.| 135| | void SetChainId(uint64_t chainId) | Sets the call chain ID in the **HiTraceId** object.<br>Input arguments:<br>- **chainId**: call chain ID.<br>Output arguments: none<br>Return value: none| 136| | uint64_t GetSpanId() | Obtains the span ID from the current **HiTraceId** object.<br>Input arguments: none<br>Output arguments: none<br>Return value: current span ID.| 137| | void SetSpanId(uint64_t spanId) | Sets the span ID in the **HiTraceId** object.<br>Input arguments:<br>- **spanId**: span ID.<br>Output arguments: none<br>Return value: none| 138| | uint64_t GetParentSpanId() | Obtains the parent span ID from the current **HiTraceId** object.<br>Input arguments: none<br>Output arguments: none<br>Return value: parent span ID.| 139| | void SetParentSpanId(uint64_t parentSpanId) | Sets the parent span ID in the **HiTraceId** object.<br>Input arguments:<br>- **parentSpanId**: parent span ID.<br>Output arguments: none<br>Return value: none| 140| | int ToBytes(uint8_t* pIdArray, int len) | Converts the **HiTraceId** object into a byte array to facilitate caching or communication transfer.<br>Input arguments:<br>- **pIdArray**: pointer to a byte array. The minimum length of the byte array is **HITRACE_ID_LEN**.<br>- **len**: length of the byte array.<br>Output parameters:<br>- **pIdArray**: pointer to a byte array. If the object is valid, the object data after conversion is stored.<br>Return value: a value greater than **0** (indicating a valid array of object data) if the conversion is successful; **0** otherwise.| 141 142 143### Call Chain Processing 144 145Inter-device, inter-process, and inter-thread calls are implemented through the communication mechanism. HiTraceChain requires transfer of **traceid** in the communication mechanism. 146 147Some built-in communication mechanisms (such as ZIDL) of OpenHarmony already support the transfer of **traceid**. 148 149The following figure shows the process of transferring **traceid** in synchronous call. The process of transferring **traceid** in asynchronous call is similar. 150 151 Extended communication mechanisms can also follow this implementation. 152 153 **Figure 5** Call chain trace in synchronous communication 154 155  156 157The process is as follows: 158 1591. The service module on the client calls the **begin()** function to start call chain trace. 160 1612. The service module on the client synchronously calls the **transact** function to the communication component on the client. 162 1633. The communication component on the client performs the following: 164 1. Obtains **traceid** from the TLS of the calling thread. 165 2. Generates child **traceid**. 166 3. Writes child **traceid** into the transaction data (synchronous communication data). 167 4. Performs CS trace. 168 5. Sends communication data to the communication component on the server. 169 1704. On receiving the communication data, the communication component on the server performs the following: 171 1. Obtains **traceid** from the data message package. 172 2. Sets **traceid** in the TLS of the calling thread. 173 3. Performs SR trace. 174 4. Synchronously calls the **onTransact** callback to the service module on the server. 175 1765. The service module on the server processes the service and sends the transact reply message carrying the processing result to the communication component. 177 1786. The communication component on the server performs the following: 179 1. Performs SS trace. 180 2. Sends communication data to the communication component on the client. 181 3. Clears **traceid** from the TLS of the calling thread. 182 1837. On receiving the communication data, the communication component on the client performs the following: 184 1. Performs CR trace. 185 2. Sends a transact reply response to the service module on the client. 186 1878. The service module on the client processes the transact reply response. 188 1899. When the process ends, the service module on the client calls the **end()** function to stop call chain trace. 190 191 192## How to Develop 193 194 195### **C++** 196 1971. Develop the source code. 198 Include the **hitracechain** header file in the class definition header file or class implementation source file. For example: 199 200 ``` 201 #include "hitrace/tracechain.h" 202 ``` 203 204 Add the code to start and stop call chain trace in the class implementation source file. 205 206 ``` 207 using namespace OHOS::HiviewDFX; 208 auto traceId = HiTraceChain::Begin("MyServiceFlow", HITRACE_FLAG_DEFAULT); 209 ...... 210 HiTraceChain::End(traceId); 211 ``` 212 2132. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. 214 215 ``` 216 external_deps = [ "hiviewdfx:libhitracechain" ] 217 ``` 218 219 220### **C** 221 2221. Develop the source code. 223 Include the **hitracechain** header file in the source file. 224 225 ``` 226 #include "hitrace/tracechain.h" 227 ``` 228 229 Add the code to start and stop call chain trace in the class implementation source file. 230 231 ``` 232 HiTraceIdStruct traceId = HiTraceChainBegin("MyServiceFlow", HITRACE_FLAG_DEFAULT); 233 ...... 234 HiTraceChainEnd(traceId); 235 ``` 236 2372. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. 238 239 ``` 240 external_deps = [ "hiviewdfx:libhitracechain" ] 241 ``` 242
