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| --start_bgsrv | Enables trace collection in snapshot mode.|
27| --dump_bgsrv | Triggers trace output to a file in snapshot mode.|
28| --stop_bgsrv | Disables trace collection in snapshot mode.|
29
30> **Description**
31>
32> The snapshot mode is a trace collection service with a fixed trace tag. By default, the trace data is not stored. You can run the **--dump_bgsrv** command to trigger trace dump at the current time. The trace file is in binary format and is generated in **/data/log/hitrace** by default. The file name format is **trace-YYMMDDHHmmSS@[BOOT_TIME].sys**. You can view the file using [SmartPerf](https://www.smartperf.host).
33
34## Examples
35
36Run the following commands in the hdc shell:
37
381. Run the **hitrace -l** command to display the tag list.
39
40   ![](figures/hitrace-l.png)
41
422. Run the **hitrace --trace_begin app** command to start capturing trace data of the application.
43
44   ![](figures/hitrace-begin-app.png)
45
463. Run the **hitrace --trace_finish** or **hitrace --trace_finish -o /data/local/tmp/test.ftrace** 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.
47
48   ![](figures/hitrace-finish.png)
49
504. Run the **hitrace -b 10240 -t 10 -o /data/local/tmp/test2.ftrace app ability** command to capture trace data with the following settings:
51
52   ![](figures/hitrace-b.png)
53
54   - Buffer size: 10240 KB
55   - Trace uptime: 10s
56   - Output path: **/data/local/tmp/test1.htrace**
57   - Tags: app and ability
58
595. Run the **hitrace --trace_dump** or **hitrace --trace_dump -o /data/local/tmp/test3.ftrace** 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.
60
61   ![](figures/hitrace-dump.png)
62
63   You can also run the **hitrace --trace_dump |grep \*\*\*** command to dump trace data based on keywords.
64
656. Run the **hitrace --start_bgsrv** command to enable trace collection in snapshot mode.
66
67   ![](figures/hitrace-start_bgsrv.png)
68
697. Run the **hitrace --dump_bgsrv** command to enable trace collection in snapshot mode.
70
71   By default, the trace information is stored in **/data/log/hitrace/**, which is in binary format. The file is named in the format of **trace-YYMMDDHHmmSS@[BOOT_TIME].sys**. You can view the file using [SmartPerf](https://www.smartperf.host).
72
73   ![](figures/hitrace-dump_bgsrv.png)
74
758. Run the **hitrace --stop_bgsrv** command to disable trace collection in snapshot mode.
76
77   ![](figures/hitrace-stop_bgsrv.png)
78