<tbody><trid="row17736152318398"><tdclass="cellrowborder"valign="top"width="25%"headers="mcps1.2.5.1.1 "><pid="p1110983610395"><aname="p1110983610395"></a><aname="p1110983610395"></a>Full code base (for mini, small, and standard systems)</p>
<trid="row14814218214"><tdclass="cellrowborder"valign="top"width="25%"headers="mcps1.2.5.1.1 "><pid="p2481132228"><aname="p2481132228"></a><aname="p2481132228"></a>Standard system solution (binary)</p>
<trid="row17736152318398"><tdclass="cellrowborder"valign="top"width="25%"><pid="p1110983610395"><aname="p1110983610395"></a><aname="p1110983610395"></a>Full code (for mini, small, and standard systems)</p>
<trid="row14814218214"><tdclass="cellrowborder"valign="top"width="25%"><pid="p2481132228"><aname="p2481132228"></a><aname="p2481132228"></a>Standard system solution (binary)</p>
<trid="row18518114121312"><tdclass="cellrowborder"valign="top"width="25%"headers="mcps1.2.5.1.1 "><pid="p4437184283419"><aname="p4437184283419"></a><aname="p4437184283419"></a>Full code base (for mini, small, and standard systems)</p>
<trid="row461814235717"><tdclass="cellrowborder"valign="top"width="25%"headers="mcps1.2.5.1.1 "><pid="p0618124216579"><aname="p0618124216579"></a><aname="p0618124216579"></a>Hi3516 standard system solution (binary)</p>
<trid="row162201392319"><tdclass="cellrowborder"valign="top"width="25%"headers="mcps1.2.5.1.1 "><pid="p2220191315"><aname="p2220191315"></a><aname="p2220191315"></a>RK3568 standard system solution (binary)</p>
<trid="row18518114121312"><tdclass="cellrowborder"valign="top"width="25%"><pid="p4437184283419"><aname="p4437184283419"></a><aname="p4437184283419"></a>Beta version (for standard systems)</p>
HiCollie provides the software watchdog function. It provides a unified framework for fault detection and fault log generation to help you locate software timeout faults resulting from system service deadlock, application main thread blocking, and service process timeout.
## Available APIs<a name="section139261151145116"></a>
<tdclass="cellrowborder"valign="top"width="44.47555244475552%"headers="mcps1.2.4.1.3 "><pid="p18700175062115"><aname="p18700175062115"></a><aname="p18700175062115"></a>Provides the callback of the suspension detection result.</p>
<tdclass="cellrowborder"valign="top"width="44.47555244475552%"headers="mcps1.2.4.1.3 "><pid="p127630177475"><aname="p127630177475"></a><aname="p127630177475"></a>Provides the callback of the thread suspension detection result.</p>
<tdclass="cellrowborder"valign="top"width="35.82641735826417%"headers="mcps1.2.4.1.2 "><pid="p16289114074812"><aname="p16289114074812"></a><aname="p16289114074812"></a>void RegisterXCollieChecker(const sptr<XCollieChecker>&checker, unsigned int type)</p>
</td>
<tdclass="cellrowborder"valign="top"width="44.47555244475552%"headers="mcps1.2.4.1.3 "><pid="p186437319482"><aname="p186437319482"></a><aname="p186437319482"></a>Registers the callback of the thread suspension detection result.</p>
<aname="ul7783192181413"></a><aname="ul7783192181413"></a><ulid="ul7783192181413"><li><strongid="b64637561712"><aname="b64637561712"></a><aname="b64637561712"></a>checker</strong>: Indicates the pointer to the XCollieChecker instance.</li><li><strongid="b1947711661711"><aname="b1947711661711"></a><aname="b1947711661711"></a>type</strong>: Indicates the suspension detection type. Set it to <strongid="b259214119717"><aname="b259214119717"></a><aname="b259214119717"></a>XCOLLIE_THREAD</strong>.</li></ul>
<aname="ul845512153147"></a><aname="ul845512153147"></a><ulid="ul845512153147"><li><strongid="b44651010141715"><aname="b44651010141715"></a><aname="b44651010141715"></a>name</strong>: Indicates the timer name.</li><li><strongid="b266981221717"><aname="b266981221717"></a><aname="b266981221717"></a>timeout</strong>: Indicates the timeout duration, in seconds.</li><li><strongid="b17158171421710"><aname="b17158171421710"></a><aname="b17158171421710"></a>func</strong>: Indicates the timeout callback.</li><li><strongid="b1950162581810"><aname="b1950162581810"></a><aname="b1950162581810"></a>arg</strong>: Indicates the pointer to the timeout callback.</li><li><strongid="b4949151521714"><aname="b4949151521714"></a><aname="b4949151521714"></a>flag</strong>: Indicates the timer operation type.<pid="p1242762435310"><aname="p1242762435310"></a><aname="p1242762435310"></a>XCOLLIE_FLAG_DEFAULT // Indicates the default flag, which is the combination of the other three options.</p>
<pid="p1542712435312"><aname="p1542712435312"></a><aname="p1542712435312"></a>XCOLLIE_FLAG_NOOP // Calls only the timeout callback.</p>
<pid="p15427112416531"><aname="p15427112416531"></a><aname="p15427112416531"></a>XCOLLIE_FLAG_LOG // Generates a timeout fault log.</p>
<pid="p242762455314"><aname="p242762455314"></a><aname="p242762455314"></a>XCOLLIE_FLAG_RECOVERY // Exits the process.</p>
<pid="p144271424155316"><aname="p144271424155316"></a><aname="p144271424155316"></a>Return value: Returns the timer ID if the operation is successful; returns <strongid="b2229713291"><aname="b2229713291"></a><aname="b2229713291"></a>-1</strong> otherwise.</p>
<aname="ul1628783221411"></a><aname="ul1628783221411"></a><ulid="ul1628783221411"><li><strongid="b61651021161710"><aname="b61651021161710"></a><aname="b61651021161710"></a>id</strong>: Indicates the timer ID.</li><li><strongid="b24661423141717"><aname="b24661423141717"></a><aname="b24661423141717"></a>timeout</strong>: Indicates the timeout duration, in seconds.</li></ul>
<pid="p38311853105716"><aname="p38311853105716"></a><aname="p38311853105716"></a>Return value: Returns <strongid="b95701352192819"><aname="b95701352192819"></a><aname="b95701352192819"></a>true</strong> if the operation is successful; returns <strongid="b175761652152814"><aname="b175761652152814"></a><aname="b175761652152814"></a>false</strong> otherwise.</p>
<pid="p9311488283"><aname="p9311488283"></a><aname="p9311488283"></a><strongid="b9666749171816"><aname="b9666749171816"></a><aname="b9666749171816"></a>id</strong>: Indicates the timer ID.</p>
This function requires you to implement two callback functions: **CheckBlock** and **CheckThreadBlock** of the **XCollieChecker** class. After the callbacks are implemented, you need to use the **RegisterXCollieChecker** function of the **XCollie** class to register their instances. The suspension monitoring thread periodically executes all successfully registered callbacks, checks the thread logic completion flag, and determines whether the service logic of any registered thread is suspended.
1. Develop the source code.
Include the **xcollie** header file in the source file.
```
#include "xcollie.h"
```
Add the following code to the service code:
```
void MyXCollieChecker::CheckLock()
{
/* time consuming job */
}
void MyXCollieChecker::CheckThreadBlock()
{
/* time consuming job */
}
sptr<XCollieChecker> checker = new MyXCollieChecker("MyXCollieChecker");
You can add a maximum of 128 timers for a single process by using the **SetTimer** function. Adding timers will fail if the number of timers has reached the upper limit.
1. Develop the source code.
Include the **xcollie** header file in the source file.
# Development Guidelines on HiLog\_Lite<a name="EN-US_TOPIC_0000001089263241"></a>
# Development Guidelines on HiLog\_Lite<a name="EN-US_TOPIC_0000001185815838"></a>
-[Overview](#section775017517390)
-[Available APIs](#section114412157402)
...
...
@@ -6,7 +6,7 @@
## Overview<a name="section775017517390"></a>
HiLog\_Lite is the HiLog framework for Mini-System Devices \(reference memory ≥ 128 KB\) and Small-System Devices \(reference memory ≥ 1 MB\). It implements functions such as log printing, log output, and flow control.
HiLog\_Lite is the HiLog framework for Mini-System Devices \(reference memory ≥ 128 KiB\) and Small-System Devices \(reference memory ≥ 1 MiB\). It implements functions such as log printing, log output, and flow control.
## Available APIs<a name="section114412157402"></a>
HiSysEvent supports listening for events across processes. You can register a listener to listen for concerned events on a real-time basis. For example, you can enable the battery module to listen for power consumption event for power usage analysis.
## Available APIs<a name="section0342191810519"></a>
<tdclass="cellrowborder"valign="top"width="51.88%"headers="mcps1.2.3.1.2 "><pid="p14727325133216"><aname="p14727325133216"></a><aname="p14727325133216"></a>Registers a listener for system events. You can listen for certain events by specifying rules.</p>
<aname="ul6717142214919"></a><aname="ul6717142214919"></a><ulid="ul6717142214919"><li><strongid="b5330432115819"><aname="b5330432115819"></a><aname="b5330432115819"></a>listener</strong>: callback object for system events.</li><li><strongid="b1518805912597"><aname="b1518805912597"></a><aname="b1518805912597"></a>rules</strong>: rules for event listening.</li></ul>
<aname="ul12105842111913"></a><aname="ul12105842111913"></a><ulid="ul12105842111913"><li><strongid="b117641849702"><aname="b117641849702"></a><aname="b117641849702"></a>0</strong>: Repeated registration is successful.</li><li><strongid="b2682415314"><aname="b2682415314"></a><aname="b2682415314"></a>1</strong>: Initial registration is successful.</li><li>Other values: Registration has failed.</li></ul>
<tdclass="cellrowborder"valign="top"width="51.88%"headers="mcps1.2.3.1.2 "><pid="p1104194420248"><aname="p1104194420248"></a><aname="p1104194420248"></a>Removes the listener for system events.</p>
<aname="ul894321075411"></a><aname="ul894321075411"></a><ulid="ul894321075411"><li><strongid="b178371510181317"><aname="b178371510181317"></a><aname="b178371510181317"></a>listener</strong>: callback object for system events.</li></ul>
<tdclass="cellrowborder"valign="top"width="51.89%"headers="mcps1.2.3.1.2 "><pid="p94416160565"><aname="p94416160565"></a><aname="p94416160565"></a>Rule type. The matching scope includes <strongid="b638713414175"><aname="b638713414175"></a><aname="b638713414175"></a>domain</strong> and <strongid="b128648618171"><aname="b128648618171"></a><aname="b128648618171"></a>eventName</strong>. The value can be any of the following:</p>
<tdclass="cellrowborder"valign="top"width="51.89%"headers="mcps1.2.3.1.2 "><aname="ul14905926102311"></a><aname="ul14905926102311"></a><ulid="ul14905926102311"><li><strongid="b152431514132110"><aname="b152431514132110"></a><aname="b152431514132110"></a>domain</strong>: domain to which the event belongs. By default, an empty string indicates that the domain is successfully matched.</li></ul>
<tdclass="cellrowborder"valign="top"width="51.89%"headers="mcps1.2.3.1.2 "><aname="ul248063132319"></a><aname="ul248063132319"></a><ulid="ul248063132319"><li><strongid="b197622401229"><aname="b197622401229"></a><aname="b197622401229"></a>eventName</strong>: event name. By default, an empty string indicates that the event name is successfully matched.</li></ul>
<tdclass="cellrowborder"valign="top"width="51.74999999999999%"headers="mcps1.2.3.1.2 "><pid="p1772213111011"><aname="p1772213111011"></a><aname="p1772213111011"></a>Callback object for system events.</p>
HiSysEvent provides event logging APIs for OpenHarmony to record important information of key processes during system running, helping you locate faults. In addition, you can upload the log data to the cloud for big data analytics.
## Available APIs<a name="section13480315886"></a>
The following table lists the C++ APIs provided by the **HiSysEvent** class.
For details about the **HiSysEvent** class, see the API reference.
<tdclass="cellrowborder"valign="top"width="42.61%"headers="mcps1.2.3.1.2 "><pid="p14727325133216"><aname="p14727325133216"></a><aname="p14727325133216"></a>Logs system events.</p>
<aname="ul0727102516327"></a><aname="ul0727102516327"></a><ulid="ul0727102516327"><li><strongid="b738811554915"><aname="b738811554915"></a><aname="b738811554915"></a>domain</strong>: Indicates the domain related to the event. You can use a preconfigured domain or customize a domain as needed. The name of a custom domain can contain a maximum of 16 characters, including digits (0-9) and uppercase letters (A-Z). It must start with a letter.</li><li><strongid="b6556916144913"><aname="b6556916144913"></a><aname="b6556916144913"></a>eventName</strong>: Indicates the event name. The value contains a maximum of 32 characters, including digits (0 to 9), letters (A-Z), and underscore (_). It must start with a letter and cannot end with an underscore (_).</li><li><strongid="b23385182493"><aname="b23385182493"></a><aname="b23385182493"></a>type</strong>: Indicates the event type. For details, see <strongid="b137231746124214"><aname="b137231746124214"></a><aname="b137231746124214"></a>EventType</strong>.</li><li><strongid="b8262191944912"><aname="b8262191944912"></a><aname="b8262191944912"></a>keyValues</strong>: Indicates the key-value pairs of event parameters. It can be in the format of the basic data type, <strongid="b1270524734214"><aname="b1270524734214"></a><aname="b1270524734214"></a>std::string</strong>, <strongid="b1870517478422"><aname="b1870517478422"></a><aname="b1870517478422"></a>std::vector<emid="i5705114724211"><aname="i5705114724211"></a><aname="i5705114724211"></a><basic data type></em></strong>, or <strongid="b2070614724211"><aname="b2070614724211"></a><aname="b2070614724211"></a>std:vector<std::string></strong>. The value contains a maximum of 48 characters, including digits (0 to 9), letters (A-Z), and underscore (_). It must start with a letter and cannot end with an underscore (_). The number of parameter names cannot exceed 32.</li></ul>
<pid="p1727152513217"><aname="p1727152513217"></a><aname="p1727152513217"></a>Return value: Returns <strongid="b1893811237358"><aname="b1893811237358"></a><aname="b1893811237358"></a>0</strong> if the operation is successful; returns a value less than <strongid="b99381232350"><aname="b99381232350"></a><aname="b99381232350"></a>0</strong> otherwise.</p>
</td>
</tr>
</tbody>
</table>
**Table 2** Description of HiSysEvent::Domain APIs
<tdclass="cellrowborder"valign="top"width="42.61%"headers="mcps1.2.3.1.2 "><pid="p621693417364"><aname="p621693417364"></a><aname="p621693417364"></a>Distributed data management subsystem</p>
<tdclass="cellrowborder"valign="top"width="42.61%"headers="mcps1.2.3.1.2 "><pid="p1121716345369"><aname="p1121716345369"></a><aname="p1121716345369"></a>Smart TV subsystem</p>
<tdclass="cellrowborder"valign="top"width="42.61%"headers="mcps1.2.3.1.2 "><pid="p18219143493618"><aname="p18219143493618"></a><aname="p18219143493618"></a>Wearable-dedicated service subsystem</p>
## How to Develop<a name="section112771171317"></a>
**C++**
1. Develop the source code.
Include the **HiSysEvent** header file in the class definition header file or class implementation source file. For example:
```
#include "hisysevent.h"
```
Add the event logging code. For example, if you want to log events specific to the app start time \(**start\_app**\), then add the following code to the service implementation source file:
HiSysEvent provides an API for you to query system events. You can query concerned events by specifying search criteria. For example, for a power consumption module, you can query required system events for analysis.
## Available APIs<a name="section03869128521"></a>
<tdclass="cellrowborder"valign="top"width="51.88%"headers="mcps1.2.3.1.2 "><pid="p14727325133216"><aname="p14727325133216"></a><aname="p14727325133216"></a>Queries system events by specifying search criteria such as the time segment, event domain, and event name.</p>
<tbody><trid="row3784451122012"><tdclass="cellrowborder"valign="top"width="47.85%"headers="mcps1.2.3.1.1 "><pid="p2078414512209"><aname="p2078414512209"></a><aname="p2078414512209"></a>long long beginTime</p>
<trid="row1564913158230"><tdclass="cellrowborder"valign="top"width="47.85%"headers="mcps1.2.3.1.1 "><pid="p11649191511239"><aname="p11649191511239"></a><aname="p11649191511239"></a>long long endTime</p>
<tdclass="cellrowborder"valign="top"width="52.15%"headers="mcps1.2.3.1.2 "><pid="p1161901214232"><aname="p1161901214232"></a><aname="p1161901214232"></a>Maximum number of query records.</p>
<tdclass="cellrowborder"valign="top"width="51.970000000000006%"headers="mcps1.2.3.1.2 "><pid="p94416160565"><aname="p94416160565"></a><aname="p94416160565"></a>Rule type. The default value is <strongid="b196007205817"><aname="b196007205817"></a><aname="b196007205817"></a>0</strong>.</p>
<tdclass="cellrowborder"valign="top"width="51.970000000000006%"headers="mcps1.2.3.1.2 "><aname="ul14905926102311"></a><aname="ul14905926102311"></a><ulid="ul14905926102311"><li><strongid="b9813231789"><aname="b9813231789"></a><aname="b9813231789"></a>domain</strong>: domain to which the event belongs. By default, an empty string indicates that the domain is successfully matched.</li></ul>
<tdclass="cellrowborder"valign="top"width="51.970000000000006%"headers="mcps1.2.3.1.2 "><aname="ul248063132319"></a><aname="ul248063132319"></a><ulid="ul248063132319"><li><strongid="b172129351784"><aname="b172129351784"></a><aname="b172129351784"></a>eventList</strong>: event name list. By default, an empty string indicates that the event names on the list are successfully matched.</li></ul>
<tdclass="cellrowborder"valign="top"width="51.970000000000006%"headers="mcps1.2.3.1.2 "><pid="p126315352130"><aname="p126315352130"></a><aname="p126315352130"></a>Callback object for completion of event query.</p>
<aname="ul106383518130"></a><aname="ul106383518130"></a><ulid="ul106383518130"><li><strongid="b855743017177"><aname="b855743017177"></a><aname="b855743017177"></a>reason</strong>: reason for completion of event query. The default value is <strongid="b5175337111718"><aname="b5175337111718"></a><aname="b5175337111718"></a>0</strong>.</li><li><strongid="b1196583151911"><aname="b1196583151911"></a><aname="b1196583151911"></a>total</strong>: total number of events returned in this query.</li></ul>
The HiSysEvent tool is a command line tool preconfigured in the system. You can specify search criteria to query system events that meet your requirement. Using this tool, you can debug event logging during development or query system events for fault locating.
## Usage<a name="section1210623418527"></a>
1. Run the HiSysEvent tool.
The tool is preconfigured in the **/system/bin** directory. You can run the following command in any directory:
In the preceding command, parameters **-s** and **-e** specify the start time and end time, respectively. If **-s** or **-e** is not specified, there is no limitation for the start time or end time.
Parameter **-m** specifies the maximum number of event records that can be returned in this query.
HiSysEvent provides event logging APIs for OpenHarmony to record important information of key processes during system running, helping you locate faults. In addition, you can upload the log data to the cloud for big data analytics.
-**[HiSysEvent Query](hisysevent-query.md)**
## Available APIs<a name="section13480315886"></a>
The following table lists the C++ APIs provided by the **HiSysEvent** class.
For details about the **HiSysEvent** class, see the API reference.
<tdclass="cellrowborder"valign="top"width="42.61%"headers="mcps1.2.3.1.2 "><pid="p14727325133216"><aname="p14727325133216"></a><aname="p14727325133216"></a>Logs system events.</p>
<aname="ul0727102516327"></a><aname="ul0727102516327"></a><ulid="ul0727102516327"><li>domain: Indicates the domain related to the event. You can use a preconfigured domain or customize a domain as needed. The name of a custom domain can contain a maximum of 16 characters, including digits (0-9) and uppercase letters (A-Z). It must start with a letter.</li><li>eventName: Indicates the event name. The value contains a maximum of 32 characters, including digits (0 to 9), lowercase letters (a-z), uppercase letters (A-Z), and underscores (_). It must start with a letter and cannot end with an underscore (_).</li><li>type: Indicates the event type. For details, see <strongid="b137231746124214"><aname="b137231746124214"></a><aname="b137231746124214"></a>EventType</strong>.</li><li>keyValues: Indicates the key-value pairs of event parameters. It can be in the format of the basic data type, <strongid="b1270524734214"><aname="b1270524734214"></a><aname="b1270524734214"></a>std::string</strong>, <strongid="b1870517478422"><aname="b1870517478422"></a><aname="b1870517478422"></a>std::vector<emid="i5705114724211"><aname="i5705114724211"></a><aname="i5705114724211"></a><basic data type></em></strong>, or <strongid="b2070614724211"><aname="b2070614724211"></a><aname="b2070614724211"></a>std:vector<std::string></strong>. The value contains a maximum of 48 characters, including digits (0 to 9), lowercase letters (a-z), uppercase letters (A-Z), and underscores (_). It must start with a letter and cannot end with an underscore (_). The number of parameter names cannot exceed 32.</li></ul>
<pid="p1727152513217"><aname="p1727152513217"></a><aname="p1727152513217"></a>Return value: Returns <strongid="b1893811237358"><aname="b1893811237358"></a><aname="b1893811237358"></a>0</strong> if the operation is successful; returns a value less than <strongid="b99381232350"><aname="b99381232350"></a><aname="b99381232350"></a>0</strong> otherwise.</p>
</td>
</tr>
</tbody>
</table>
**Table 2** Description of HiSysEvent::Domain APIs
<tdclass="cellrowborder"valign="top"width="42.61%"headers="mcps1.2.3.1.2 "><pid="p621693417364"><aname="p621693417364"></a><aname="p621693417364"></a>Distributed data management subsystem</p>
<tdclass="cellrowborder"valign="top"width="42.61%"headers="mcps1.2.3.1.2 "><pid="p1121716345369"><aname="p1121716345369"></a><aname="p1121716345369"></a>Smart TV subsystem</p>
<tdclass="cellrowborder"valign="top"width="42.61%"headers="mcps1.2.3.1.2 "><pid="p18219143493618"><aname="p18219143493618"></a><aname="p18219143493618"></a>Wearable-dedicated service subsystem</p>
## How to Develop<a name="section112771171317"></a>
**C++**
1. Develop the source code.
Include the **HiSysEvent** header file in the class definition header file or class implementation source file. For example:
```
#include "hisysevent.h"
```
Add the event logging code. For example, if you want to log events specific to the app start time \(start\_app\), then add the following code to the service implementation source file:
HiTrace 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.
## Use Cases<a name="section134561822574"></a>
HiTrace can be used for the following purposes:
- Associates and reports service process information \(such as logs and events\) on the device.
- Displays and analyzes reported information on the cloud to facilitate fault location.
- Works with the IDE to debug the detailed service process and time consumption distribution for system optimization.
**Figure 1** Use cases of HiTrace<a name="fig179241023125715"></a>
1. 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.
**Figure 3** Service calling process<a name="fig205051834145813"></a>
2. Add **traceid** to logs and events automatically to facilitate comprehensive analysis and quick fault location.
## Available APIs<a name="section1517945334617"></a>
HiTrace provides C++ and C APIs. The upper-layer services mainly use HiTrace to start and stop call chain tracing.
HiTrace 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.
### Java, C++, and C APIs<a name="section932504474"></a>
<tdclass="cellrowborder"valign="top"width="31.430000000000003%"headers="mcps1.2.4.1.2 "><pid="p198391118193717"><aname="p198391118193717"></a><aname="p198391118193717"></a>HiTraceId Begin(const std::string& name, int flags)</p>
</td>
<tdclass="cellrowborder"valign="top"width="58.77%"headers="mcps1.2.4.1.3 "><pid="p684013182375"><aname="p684013182375"></a><aname="p684013182375"></a>Starts HiTrace, generates a <strongid="b2063619462230"><aname="b2063619462230"></a><aname="b2063619462230"></a>HiTraceId</strong> object, and sets it in the TLS of the calling thread.</p>
<aname="ul1537854218177"></a><aname="ul1537854218177"></a><ulid="ul1537854218177"><li><strongid="b1566312131676"><aname="b1566312131676"></a><aname="b1566312131676"></a>name</strong>: Indicates the name of the service process.</li><li><strongid="b75512128711"><aname="b75512128711"></a><aname="b75512128711"></a>flags</strong>: Indicates tracing flags, which can be used in combination. <aname="ul18842248101915"></a><aname="ul18842248101915"></a><ulid="ul18842248101915"><li>HITRACE_FLAG_INCLUDE_ASYNC: Traces both synchronous and asynchronous calls. By default, only synchronous calls are traced.</li><li><strongid="b724616241477"><aname="b724616241477"></a><aname="b724616241477"></a>HITRACE_FLAG_DONOT_CREATE_SPAN</strong>: Do not create a span. By default, a span is created.</li><li><strongid="b136181926479"><aname="b136181926479"></a><aname="b136181926479"></a>HITRACE_FLAG_TP_INFO</strong>: Outputs the tracepoint information. By default, the information is not output.</li><li><strongid="b358818291777"><aname="b358818291777"></a><aname="b358818291777"></a>HITRACE_FLAG_NO_BE_INFO</strong>: Do not output the start and end information. By default, the information is output.</li><li><strongid="b38571331974"><aname="b38571331974"></a><aname="b38571331974"></a>HITRACE_FLAG_DONOT_ENABLE_LOG</strong>: Do not associate logs for output. By default, logs are associated for output.</li><li><strongid="b17320371870"><aname="b17320371870"></a><aname="b17320371870"></a>HITRACE_FLAG_FAULT_TRIGGER</strong>: Triggers tracing by fault. By default, tracing is triggered normally.</li><li><strongid="b876915381711"><aname="b876915381711"></a><aname="b876915381711"></a>HITRACE_FLAG_D2D_TP_INFO</strong>: Outputs the device-to-device tracepoint information. By default, the information is not output.</li><li><strongid="b66510421776"><aname="b66510421776"></a><aname="b66510421776"></a>HITRCE_FLAG_DEFAULT</strong>: Indicates the default flag.</li></ul>
</li><li>Output arguments: none</li><li>Return value: Returns a valid <strongid="b7411101522917"><aname="b7411101522917"></a><aname="b7411101522917"></a>HiTraceId</strong> object if call chain tracing is triggered successfully; returns an invalid object otherwise.</li></ul>
<pid="p188401918203713"><aname="p188401918203713"></a><aname="p188401918203713"></a>Note: In nested tracing mode, an invalid object will be returned if tracing is started at the nested layer.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p3840181820372"><aname="p3840181820372"></a><aname="p3840181820372"></a>Stops HiTrace based on the <strongid="b1605239122415"><aname="b1605239122415"></a><aname="b1605239122415"></a>HiTraceId</strong> object returned by the <strongid="b7610183992419"><aname="b7610183992419"></a><aname="b7610183992419"></a>Begin</strong> API, and clears the <strongid="b1610173918241"><aname="b1610173918241"></a><aname="b1610173918241"></a>HiTraceId</strong> object in the TLS of the calling thread.</p>
<aname="ul2917140133015"></a><aname="ul2917140133015"></a><ulid="ul2917140133015"><li><strongid="b8201185118711"><aname="b8201185118711"></a><aname="b8201185118711"></a>id</strong>: Indicates the <strongid="b2071183114331"><aname="b2071183114331"></a><aname="b2071183114331"></a>HiTraceId</strong> object.</li></ul>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p98401818123720"><aname="p98401818123720"></a><aname="p98401818123720"></a>Obtains the <strongid="b98371719256"><aname="b98371719256"></a><aname="b98371719256"></a>HiTraceId</strong> object from the TLS of the calling thread.</p>
<pid="p9840418133716"><aname="p9840418133716"></a><aname="p9840418133716"></a>Return value: Returns the <strongid="b73911122162613"><aname="b73911122162613"></a><aname="b73911122162613"></a>HiTraceId</strong> object in the contextual TLS of the calling thread.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p384061893715"><aname="p384061893715"></a><aname="p384061893715"></a>Purpose: Sets the <strongid="b7405852152614"><aname="b7405852152614"></a><aname="b7405852152614"></a>HiTraceId</strong> object in the TLS of the calling thread.</p>
<aname="ul1355016467304"></a><aname="ul1355016467304"></a><ulid="ul1355016467304"><li><strongid="b648307174"><aname="b648307174"></a><aname="b648307174"></a>id</strong>: Indicates the <strongid="b492669584"><aname="b492669584"></a><aname="b492669584"></a>HiTraceId</strong> object.</li></ul>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p584019184379"><aname="p584019184379"></a><aname="p584019184379"></a>Clears the <strongid="b8445182151511"><aname="b8445182151511"></a><aname="b8445182151511"></a>HiTraceId</strong> object in the TLS of the current thread.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p984031812378"><aname="p984031812378"></a><aname="p984031812378"></a>Obtains the span ID from the current <strongid="b186741420142718"><aname="b186741420142718"></a><aname="b186741420142718"></a>HiTraceId</strong> object.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p88419184373"><aname="p88419184373"></a><aname="p88419184373"></a>Outputs HiTrace call chain information based on the information type. The information includes the timestamp and <strongid="b185817437323"><aname="b185817437323"></a><aname="b185817437323"></a>HiTraceId</strong> object information of the span.</p>
<aname="ul18619103153812"></a><aname="ul18619103153812"></a><ulid="ul18619103153812"><li><strongid="b7818831083"><aname="b7818831083"></a><aname="b7818831083"></a>type</strong>: Indicates the information type. The options are as follows:<aname="ul1941510328297"></a><aname="ul1941510328297"></a><ulid="ul1941510328297"><li><strongid="b18809161180"><aname="b18809161180"></a><aname="b18809161180"></a>HITRACE_TP_CS</strong>: Client Send, which indicates the messages sent by the synchronous/asynchronous communication client.</li><li><strongid="b327281271319"><aname="b327281271319"></a><aname="b327281271319"></a>HITRACE_TP_SR</strong>: Server Receive, which indicates the messages received by the server in synchronous/asynchronous communication.</li><li><strongid="b10154742682"><aname="b10154742682"></a><aname="b10154742682"></a>HITRACE_TP_SS</strong>: Server Send, which indicates the response messages sent by the server in synchronous communication.</li><li><strongid="b152598127810"><aname="b152598127810"></a><aname="b152598127810"></a>HITRACE_TP_CR</strong>: Client Receive, which indicates the response messages received by the synchronous communication client.</li><li><strongid="b82631512817"><aname="b82631512817"></a><aname="b82631512817"></a>HITRACE_TP_GENERAL</strong>: Indicates the common output information.</li></ul>
</li><li><strongid="b117401716584"><aname="b117401716584"></a><aname="b117401716584"></a>id</strong>: Indicates the ID of the current span.</li><li><strongid="b392172019813"><aname="b392172019813"></a><aname="b392172019813"></a>fmt</strong>: Indicates the string describing the format variable parameter.</li><li><strongid="b986771717818"><aname="b986771717818"></a><aname="b986771717818"></a>args</strong>: Indicates the variable parameter.</li></ul>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p68411618153713"><aname="p68411618153713"></a><aname="p68411618153713"></a>Outputs HiTrace call chain information based on the communication mode and information type. The information includes the timestamp and <strongid="b8151210123912"><aname="b8151210123912"></a><aname="b8151210123912"></a>HiTraceId</strong> object information of the span.</p>
<aname="ul914264413811"></a><aname="ul914264413811"></a><ulid="ul914264413811"><li><strongid="b76471824183"><aname="b76471824183"></a><aname="b76471824183"></a>mode</strong>: Indicates the communication mode. The options are as follows:<aname="ul137382469451"></a><aname="ul137382469451"></a><ulid="ul137382469451"><li><strongid="b13732297812"><aname="b13732297812"></a><aname="b13732297812"></a>HITRACE_CM_DEFAULT</strong>: default communication mode used when no communication mode is specified</li><li><strongid="b1820115271789"><aname="b1820115271789"></a><aname="b1820115271789"></a>HITRACE_CM_THREAD</strong>: inter-thread communication</li><li><strongid="b27781831488"><aname="b27781831488"></a><aname="b27781831488"></a>HITRACE_CM_PROCESS</strong>: inter-process communication</li><li><strongid="b15657113313819"><aname="b15657113313819"></a><aname="b15657113313819"></a>HITRACE_CM_DEVICE</strong>: inter-device communication</li></ul>
</li><li><strongid="b172723513812"><aname="b172723513812"></a><aname="b172723513812"></a>type</strong>: Indicates the information type. The options are as follows:<aname="ul19648426458"></a><aname="ul19648426458"></a><ulid="ul19648426458"><li><strongid="b26421037382"><aname="b26421037382"></a><aname="b26421037382"></a>HITRACE_TP_CS</strong>: Client Send, which indicates the messages sent by the synchronous/asynchronous communication client.</li><li><strongid="b66504018818"><aname="b66504018818"></a><aname="b66504018818"></a>HITRACE_TP_SR</strong>: Server Receive, which indicates the messages received by the server in synchronous/asynchronous communication.</li><li><strongid="b285283761"><aname="b285283761"></a><aname="b285283761"></a>HITRACE_TP_SS</strong>: Server Send, which indicates the response messages sent by the server in synchronous communication.</li><li><strongid="b148684447814"><aname="b148684447814"></a><aname="b148684447814"></a>HITRACE_TP_CR</strong>: Client Receive, which indicates the response messages received by the synchronous communication client.</li><li><strongid="b17875164618816"><aname="b17875164618816"></a><aname="b17875164618816"></a>HITRACE_TP_GENERAL</strong>: Indicates the common output information.</li></ul>
</li><li><strongid="b1216749882"><aname="b1216749882"></a><aname="b1216749882"></a>id</strong>: Indicates the ID of the current span.</li><li><strongid="b82757501383"><aname="b82757501383"></a><aname="b82757501383"></a>fmt</strong>: Indicates the string describing the format variable parameter.</li><li><strongid="b15518145114817"><aname="b15518145114817"></a><aname="b15518145114817"></a>args</strong>: Indicates the variable parameter.</li></ul>
<tdclass="cellrowborder"valign="top"width="58.77%"headers="mcps1.2.4.1.3 "><pid="p48419181372"><aname="p48419181372"></a><aname="p48419181372"></a>Represents the default constructor used to generate an invalid <strongid="b1235325844115"><aname="b1235325844115"></a><aname="b1235325844115"></a>HiTraceId</strong> object. </p>
<trid="row138418186374"><tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.1 "><pid="p19841111813712"><aname="p19841111813712"></a><aname="p19841111813712"></a>HiTraceId(const uint8_t* pIdArray, int len)</p>
</td>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p684110183377"><aname="p684110183377"></a><aname="p684110183377"></a>Represents the constructor used to create a <strongid="b1488144194216"><aname="b1488144194216"></a><aname="b1488144194216"></a>HiTraceId</strong> object based on the specified byte array. </p>
<divclass="p"id="p9841151833711"><aname="p9841151833711"></a><aname="p9841151833711"></a>Input arguments:<aname="ul783818256482"></a><aname="ul783818256482"></a><ulid="ul783818256482"><li><strongid="b1725445715818"><aname="b1725445715818"></a><aname="b1725445715818"></a>pIdArray</strong>: Indicates the pointer to a byte array.</li><li><strongid="b3437458486"><aname="b3437458486"></a><aname="b3437458486"></a>len</strong>: Indicates the length of the byte array.</li></ul>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p1084251893713"><aname="p1084251893713"></a><aname="p1084251893713"></a>Checks whether the <strongid="b18546440145116"><aname="b18546440145116"></a><aname="b18546440145116"></a>HiTraceId</strong> object is valid.</p>
<pid="p884261893710"><aname="p884261893710"></a><aname="p884261893710"></a>Return value: Returns <strongid="b20386195514314"><aname="b20386195514314"></a><aname="b20386195514314"></a>true</strong> if the <strongid="b1899544174516"><aname="b1899544174516"></a><aname="b1899544174516"></a>HiTraceId</strong> object is valid; returns <strongid="b1273655294313"><aname="b1273655294313"></a><aname="b1273655294313"></a>false</strong> otherwise.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p128421518153712"><aname="p128421518153712"></a><aname="p128421518153712"></a>Checks whether the tracing flag of the <strongid="b1014619442447"><aname="b1014619442447"></a><aname="b1014619442447"></a>HiTraceId</strong> object is enabled.</p>
<aname="ul9760031103115"></a><aname="ul9760031103115"></a><ulid="ul9760031103115"><li><strongid="b136731441791"><aname="b136731441791"></a><aname="b136731441791"></a>flag</strong>: Indicates the tracing flag. For details, see the description in the <strongid="b186672319452"><aname="b186672319452"></a><aname="b186672319452"></a>Begin</strong> function.</li></ul>
<pid="p98421318143720"><aname="p98421318143720"></a><aname="p98421318143720"></a>Return value: Returns <strongid="b151944819455"><aname="b151944819455"></a><aname="b151944819455"></a>true</strong> if the tracing flag is enabled; returns <strongid="b1619204874513"><aname="b1619204874513"></a><aname="b1619204874513"></a>false</strong> otherwise.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p1084221893717"><aname="p1084221893717"></a><aname="p1084221893717"></a>Enables the tracing flag of the <strongid="b118041135213"><aname="b118041135213"></a><aname="b118041135213"></a>HiTraceId</strong> object.</p>
<aname="ul144862816319"></a><aname="ul144862816319"></a><ulid="ul144862816319"><li><strongid="b430319434"><aname="b430319434"></a><aname="b430319434"></a>flag</strong>: Indicates the tracing flag. For details, see the description in the <strongid="b1067701187"><aname="b1067701187"></a><aname="b1067701187"></a>Begin</strong> function.</li></ul>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p12842151803718"><aname="p12842151803718"></a><aname="p12842151803718"></a>Obtains the tracing flag set in the <strongid="b36515674811"><aname="b36515674811"></a><aname="b36515674811"></a>HiTraceId</strong> object.</p>
<pid="p19842101853716"><aname="p19842101853716"></a><aname="p19842101853716"></a>Return value: Returns the combination of tracing flags. For details, see the description in the <strongid="b12693139144817"><aname="b12693139144817"></a><aname="b12693139144817"></a>Begin</strong> function.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p7842141823718"><aname="p7842141823718"></a><aname="p7842141823718"></a>Sets a tracing flag in the <strongid="b9174314814"><aname="b9174314814"></a><aname="b9174314814"></a>HiTraceId</strong> object.</p>
<aname="ul6490121183115"></a><aname="ul6490121183115"></a><ulid="ul6490121183115"><li><strongid="b1556719154919"><aname="b1556719154919"></a><aname="b1556719154919"></a>flags</strong>: Indicates the combination of tracing flags. For details, see the description in the <strongid="b469312329341"><aname="b469312329341"></a><aname="b469312329341"></a>Begin</strong> function.</li></ul>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p784271815372"><aname="p784271815372"></a><aname="p784271815372"></a>Sets the call chain ID in the <strongid="b1319041125416"><aname="b1319041125416"></a><aname="b1319041125416"></a>HiTraceId</strong> object.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p1484351820374"><aname="p1484351820374"></a><aname="p1484351820374"></a>Obtains the span ID from the current <strongid="b8123101515516"><aname="b8123101515516"></a><aname="b8123101515516"></a>HiTraceId</strong> object.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p14843171816375"><aname="p14843171816375"></a><aname="p14843171816375"></a>Sets the span ID in the <strongid="b13643024185512"><aname="b13643024185512"></a><aname="b13643024185512"></a>HiTraceId</strong> object.</p>
<aname="ul1799516134316"></a><aname="ul1799516134316"></a><ulid="ul1799516134316"><li><strongid="b43891187116"><aname="b43891187116"></a><aname="b43891187116"></a>spanId</strong>: Indicates the span ID.</li></ul>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p884381819373"><aname="p884381819373"></a><aname="p884381819373"></a>Obtains the parent span ID from the current <strongid="b5851839615"><aname="b5851839615"></a><aname="b5851839615"></a>HiTraceId</strong> object.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p1884361803719"><aname="p1884361803719"></a><aname="p1884361803719"></a>Sets the parent span ID in the <strongid="b1660960324"><aname="b1660960324"></a><aname="b1660960324"></a>HiTraceId</strong> object.</p>
<trid="row128435182379"><tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.1 "><pid="p5843181816371"><aname="p5843181816371"></a><aname="p5843181816371"></a>int ToBytes(uint8_t* pIdArray, int len)</p>
</td>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p8843171818378"><aname="p8843171818378"></a><aname="p8843171818378"></a>Converts the <strongid="b68851225439"><aname="b68851225439"></a><aname="b68851225439"></a>HiTraceId</strong> object into a byte array to facilitate caching or communication transfer.</p>
<aname="ul169461002314"></a><aname="ul169461002314"></a><ulid="ul169461002314"><li><strongid="b960934311010"><aname="b960934311010"></a><aname="b960934311010"></a>pIdArray</strong>: Indicates the pointer to a byte array. The minimum length of the byte array is <strongid="b96124430106"><aname="b96124430106"></a><aname="b96124430106"></a>HITRACE_ID_LEN</strong>.</li><li><strongid="b13672164941019"><aname="b13672164941019"></a><aname="b13672164941019"></a>len</strong>: Indicates the length of the byte array.</li></ul>
<aname="ul116274319312"></a><aname="ul116274319312"></a><ulid="ul116274319312"><li><strongid="b12376938695"><aname="b12376938695"></a><aname="b12376938695"></a>pIdArray</strong>: Indicates the pointer to a byte array. If the object is valid, the object data after conversion is stored.</li></ul>
<pid="p8843618143720"><aname="p8843618143720"></a><aname="p8843618143720"></a>Return value: Returns a value greater than 0 (indicating a valid array of object data) if the conversion is successful; returns <strongid="b2156170234"><aname="b2156170234"></a><aname="b2156170234"></a>0</strong> otherwise.</p>
Inter-device, inter-process, and inter-thread calls are implemented through the communication mechanism. **HiTrace** requires transfer of **traceid** in the communication mechanism.
Some built-in communication mechanisms \(such as ZIDL\) of OpenHarmony already support the transfer of **traceid**.
The following figure shows the process of transferring **traceid** in synchronous call. The process of transferring **traceid** in asynchronous call is similar.
Extended communication mechanisms can also follow this implementation.
**Figure 5** Call chain tracing in synchronous communication<aname="fig36822045171020"></a>
1. The service module on the client calls the **begin\(\)** function to start call chain tracing.
2. The service module on the client synchronously calls the **transact** function to the communication component on the client.
3. The communication component on the client performs the following:
1. Obtains **traceid** from the TLS of the calling thread.
2. Generates child **traceid**.
3. Writes child **traceid** into the transaction data \(synchronous communication data\).
4. Performs Client Send \(CS\) tracing.
5. Sends communication data to the communication component on the server.
4. On receiving the communication data, the communication component on the server performs the following:
1. Obtains **traceid** from the data message package.
2. Sets **traceid** in the TLS of the calling thread.
3. Performs Server Receive \(SR\) tracing.
4. Synchronously call the **onTransact** callback to the service module on the server.
5. The service module on the server processes the service and sends the transact reply message carrying the processing result to the communication component.
6. The communication component on the server performs the following:
1. Performs Server Send \(SS\) tracing.
2. Sends communication data to the communication component on the client.
3. Clears **traceid** from the TLS of the calling thread.
7. On receiving the communication data, the communication component on the client performs the following:
1. Performs Client Receive \(CR\) tracing.
2. Sends a transact reply response to the service module on the client.
8. The service module on the client processes the transact reply response.
9. When the process ends, the service module on the client calls the **end\(\)** function to stop call chain tracing.
## How to Develop<a name="section14310412491"></a>
### C++<a name="section114916381509"></a>
1. Develop the source code.
Include the **hitrace** header file in the class definition header file or class implementation source file. For example:
```
#include "hitrace/trace.h"
```
Add the code to start and stop call chain tracing in the class implementation source file.
The DFX subsystem provides the following functions:
- HiLog: Implements the logging function. It is applicable to Mini-System Devices \(reference memory ≥ 128 KB\) and Small-System Devices \(reference memory ≥ 1 MB\) as well as Standard-System Devices \(reference memory ≥ 128 MB\).
- HiLog: implements the logging function. It is applicable to Mini-System Devices \(reference memory ≥ 128 KiB\), Small-System Devices \(reference memory ≥ 1 MiB\), and Standard-System Devices \(reference memory ≥ 128 MB\).
- HiSysEvent: Implements system event logging. It is applicable to Standard-System Devices \(reference memory ≥ 128 MB\).
- HiTrace: implements distributed call chain tracing. It is applicable to Standard-System Devices \(reference memory ≥ 128 MB\).
- HiCollie: implements thread suspension detection. It is applicable to Standard-System Devices \(reference memory ≥ 128 MB\).
- HiSysEvent: implements system event logging. It is applicable to Standard-System Devices \(reference memory ≥ 128 MB\).
.png){kind=link}
.png)
