xref: /docs/en/application-dev/dfx/hitrace.md (revision e41f4b71) 
1# hitrace
2
3**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.
4
5## Prerequisites
6
7- The [environment setup](hdc.md#environment-setup) is complete.
8
9- The devices are properly connected.
10
11## Command Description
12
13| Command| Description|
14| -------- | -------- |
15| -h  | Displays help information.|
16| -l | Displays the tag list.|
17| --trace_begin | Starts capturing trace data.|
18| --trace_finish | Stops capturing trace data.|
19| --trace_dump | Dumps trace information.|
20| -b N | Sets the buffer size (in KB) for trace data. The default buffer size is 2048 KB.|
21| -t N | Sets the trace uptime in seconds, which depends on the time required for analysis. The default value is 5 seconds.|
22| -o | Specifies the target file name (**stdout** by default).|
23| -z | Compresses the trace data.|
24| --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**.|
25| --trace_finish_nodump | Stops printing when trace capturing is stopped.|
26
27## Examples
28
29Run the following commands in the hdc shell:
30
311. Run the **hitrace -l** command to display the tag list.
32
33   ![](figures/hitrace-l.png)
34
352. Run the **hitrace --trace_begin app** command to start capturing trace data of the application. 
36
37   ![](figures/hitrace-begin-app.png)
38
393. 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.
40
41   ![](figures/hitrace-finish.png)
42
434. Run the **hitrace -b 10240 -t 10 -o /data/local/tmp/test1.htrace app ability** command to capture trace data with the following settings: 
44
45
46   - Buffer size: 10240 KB
47   - Trace uptime: 10s
48   - Output path: **/data/local/tmp/test1.htrace**
49   - Tags: app and ability
50
51   ![](figures/hitrace-b.png)
525. 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.
53
54   ![](figures/hitrace-dump.png)
55
56   You can also run the **hitrace --trace_dump |grep \*\*\*** command to dump trace data based on keywords.
57