# hitrace

**HiTrace** provides APIs to implement call chain tracing throughout a service process. With this module, you can quickly obtain the run log specific to the call chain of a service process and locate faults across threads, processes, and devices.

## Prerequisites

- The [environment setup](hdc.md#environment-setup) is complete.

- The devices are properly connected.

## Command Description

| Command| Description|
| -------- | -------- |
| -h  | Displays help information.|
| -l | Displays the tag list.|
| --trace_begin | Starts capturing trace data.|
| --trace_finish | Stops capturing trace data.|
| --trace_dump | Dumps trace information.|
| -b N | Sets the buffer size (in KB) for trace data. The default buffer size is 2048 KB.|
| -t N | Sets the trace uptime in seconds, which depends on the time required for analysis. The default value is 5 seconds.|
| -o | Specifies the target file name (**stdout** by default).|
| -z | Compresses the trace data.|
| --trace_clock | Sets the type of the clock for adding a timestamp to a trace. The value can be **boot** (default), **global**, **mono**, **uptime**, or **perf**.|
| --trace_finish_nodump | Stops printing when trace capturing is stopped.|

## Examples

Run the following commands in the hdc shell:

1. Run the **hitrace -l** command to display the tag list.

   ![](figures/hitrace-l.png)

2. Run the **hitrace --trace_begin app** command to start capturing trace data of the application. 

   ![](figures/hitrace-begin-app.png)

3. Run the **hitrace --trace_finish** or **hitrace --trace_finish -o /data/local/tmp/test.htrace** command to stop capturing trace data. The former prints the captured trace data in the command-line window, and the latter outputs the data to the specified file.

   ![](figures/hitrace-finish.png)

4. Run the **hitrace -b 10240 -t 10 -o /data/local/tmp/test1.htrace app ability** command to capture trace data with the following settings: 


   - Buffer size: 10240 KB
   - Trace uptime: 10s
   - Output path: **/data/local/tmp/test1.htrace**
   - Tags: app and ability

   ![](figures/hitrace-b.png)
5. Run the **hitrace --trace_dump** or **hitrace --trace_dump -o /data/local/tmp/test2.htrace** command to dump trace data. The former dumps trace data to the command-line window, and the latter dumps trace data to the specified file.

   ![](figures/hitrace-dump.png)

   You can also run the **hitrace --trace_dump |grep \*\*\*** command to dump trace data based on keywords.