1# hitrace
2
3HiTrace为开发者提供业务流程调用链跟踪的维测接口。通过使用该接口所提供的功能，帮助开发者迅速获取指定业务流程调用链的运行日志，定位跨设备、跨进程、跨线程的故障问题。
4
5## 环境要求
6
7- 根据hdc命令行工具指导，完成[环境准备](hdc.md#环境准备)。
8
9- 正常连接设备。
10
11## 命令行说明
12
13| 命令 | 含义说明 |
14| -------- | -------- |
15| -h  | 帮助命令。 |
16| -l | 查看tag列表。 |
17| --trace_begin | 开始捕获trace。 |
18| --trace_finish | 结束捕获trace。 |
19| --trace_dump | 导出trace信息。 |
20| -b N | 设置用于存储和读取trace的缓冲区大小(buffer size KB)。默认的缓冲区大小为2048 KB。 |
21| -t N | 设置hitrace运行时长，单位为秒（默认为5秒），取决于分析所需的时间。 |
22| -o | 文件名指定目标文件的名称（默认为stdout）。 |
23| -z | 压缩捕获的跟踪。 |
24| --trace_clock | 设置向trace添加时间戳的时钟类型，可以是引导（默认）、全局、单声道、正常运行时间或性能。 |
25| --trace_finish_nodump | 停止捕获trace时不打印trace信息。 |
26| --start_bgsrv | 开启快照模式trace采集服务。 |
27| --dump_bgsrv | 触发快照模式trace输出到文件。 |
28| --stop_bgsrv | 关闭快照模式trace采集服务。 |
29
30> **说明**
31>
32> 快照模式定义为固定trace标签的trace采集服务，默认情况不落盘，开发者可通过 `--dump_bgsrv` 命令触发当前时刻的trace转储，trace为二进制格式，文件默认生成在 `/data/log/hitrace` 目录下，文件命名格式为`trace-YYMMDDHHmmSS@[BOOT_TIME].sys`。可通过[smpartperf在线工具](https://www.smartperf.host)进行查看。
33
34## 常用命令
35
36在hdc shell执行如下命令：
37
381. 查看hitrace包含的tag。
39
40   ```
41   hitrace -l
42   ```
43
44   **使用样例：**
45
46   ```
47   $ hitrace -l
48   2024/11/14 11:43:00 hitrace enter, running_state is SHOW_LIST_CATEGORY
49           tagName:   description:
50            ability - Ability Manager
51      accesscontrol - Access Control Module
52            account - Account Manager
53                ace - ACE development framework
54          animation - Animation
55                app - APP Module
56                ark - ARK Module
57          bluetooth - communicatio bluetooth
58              cloud - Cloud subsystem tag
59          cloudfile - Cloud file system
60         commercial - Commercial version tag
61      commonlibrary - commonlibrary subsystem
62             daudio - Distributed Audio
63            dcamera - Distributed Camera
64         deviceauth - Device Auth
65      devicemanager - Device Manager
66      deviceprofile - Device Profile
67              dhfwk - Distributed Hardware FWK
68             dinput - Distributed Input
69               disk - Disk I/O
70   istributeddatamgr - Distributed Data Manager
71             dlpcre - Dlp Credential Service
72                drm - Digital Rights Management
73             dsched - Distributed Schedule
74            dscreen - Distributed Screen
75               dslm - device security level
76           dsoftbus - Distributed Softbus
77               ffrt - ffrt tasks
78     filemanagement - filemanagement
79               freq - CPU Frequency
80            graphic - Graphic Module
81          gresource - Global Resource Manager
82               hdcd - hdcd
83                hdf - hdf subsystem
84               huks - Universal KeyStore
85                i2c - I2C Events
86               idle - CPU Idle
87          interconn - Interconnection subsystem
88                ipa - thermal power allocator
89                irq - IRQ Events
90             irqoff - IRQ-disabled code section tracing
91               load - CPU Load
92               mdfs - Mobile Distributed File System
93             membus - Memory Bus Utilization
94             memory - Memory
95         memreclaim - Kernel Memory Reclaim
96               misc - Misc Module
97                mmc - eMMC commands
98               msdp - Multimodal Sensor Data Platform
99    multimodalinput - HITRACE_TAG_MULTIMODALINPUT
100                net - net
101       notification - Notification Module
102               nweb - NWEB Module
103               ohos - OpenHarmony
104          pagecache - Page cache
105              power - Power Manager
106         preemptoff - Preempt-disabled code section tracing
107               push - Push subsystem
108         regulators - Voltage and Current Regulators
109                rpc - RPC and IPC
110              samgr - samgr
111              sched - CPU Scheduling
112           security - Security subsystem
113            sensors - Sensors Module
114               sync - Synchronization
115                ufs - UFS commands
116                usb - usb subsystem
117            useriam - useriam
118              virse - Virtualization Service
119             window - Window Manager
120              workq - Kernel Workqueues
121             zaudio - OpenHarmony Audio Module
122            zcamera - OpenHarmony Camera Module
123             zimage - OpenHarmony Image Module
124             zmedia - OpenHarmony Media Module
125   ```
126
1272. 开始抓指定tag的trace。
128
129   ```
130   hitrace --trace_begin --record app
131   ```
132
133   **使用样例：**
134
135   ```
136   $ hitrace --trace_begin --record app
137   2024/11/14 11:48:45 hitrace enter, running_state is RECORDING_LONG_BEGIN_RECORD
138   2024/11/14 11:48:45 args: tags:app bufferSize:18432 overwrite:1
139   2024/11/14 11:48:45 OpenRecording done.
140   ```
141
1423. 结束抓trace。
143
144   ```
145   hitrace --trace_finish --record，默认将trace信息打印在命令行窗口。
146   ```
147
148   **使用样例1：**
149
150   ```
151   $ hitrace --trace_finish --record
152   2024/11/14 11:50:33 hitrace enter, running_state is RECORDING_LONG_FINISH_RECORD
153   2024/11/14 11:50:33 capture done, output files:
154       /data/log/hitrace/record_trace_20241114115033@3010728-656499531.sys
155   ```
156
157   ```
158   hitrace --trace_finish -o /data/local/tmp/test.ftrace，添加输出路径，trace信息将导出至对应的文件中。
159   ```
160
161   **使用样例2：**
162
163   ```
164   $ hitrace --trace_finish -o /data/local/tmp/test.ftrace
165   2024/11/14 11:50:33 start to read trace.
166   2024/11/14 11:50:33 trace read done, output: /data/local/tmp/test.ftrace
167   ```
168
1694. 设置抓trace的一些信息：`hitrace -b 10240 -t 10 -o /data/local/tmp/test2.ftrace app ability`。
170
171   ```
172   hitrace -b 10240 -t 10 -o /data/local/tmp/test2.ftrace app ability。
173   ```
174
175   **使用样例：**
176
177   ```
178   $ hitrace -b 10240 -t 10 -o /data/local/tmp/test2.ftrace app ability
179   2024/11/14 11:52:13 start capture, please wait 10s ...
180   2024/11/14 11:52:23 capture done, start to read trace.
181   2024/11/14 11:52:23 trace read done, output: /data/local/tmp/test2.ftrace
182   ```
183
184   - 设置缓冲区大小为10240KB；
185   - 设置抓trace时间为10s；
186   - 设置抓完trace后文件存储在/data/local/tmp/test1.htrace中；
187   - 抓取app/ability两个tag的trace；
188
1895. 导出trace信息。
190
191   ```
192   hitrace --trace_dump，默认将信息显示在命令行窗口。
193   ```
194
195   **使用样例1：**
196
197   ```
198   $ hitrace --trace_dump
199   2024/11/14 11:54:23 start to read trace.
200   # tracer: nop
201   #
202   # entries-in-buffer/entries-written: 2/2   #P:4
203   #
204   #                                          _-----=> irqs-off
205   #                                         / _----=> need-resched
206   #                                        | / _---=> hardirq/softirq
207   #                                        || / _--=> preempt-depth
208   #                                        ||| /     delay
209   #           TASK-PID       TGID    CPU#  ||||   TIMESTAMP  FUNCTION
210   #              | |           |       |   ||||      |         |
211            <...>-21829   (  19280) [003] .... 3011033.731844: tracing_mark_write: trace_event_clock_sync: realtime_ts=1732002022239
212            <...>-21829   (  19280) [003] .... 3011033.731865: tracing_mark_write: trace_event_clock_sync: parent_ts=3011033.750000
213   #
214   ```
215
216   ```
217   hitrace --trace_dump -o /data/local/tmp/test3.ftrace，添加输出路径，trace信息将导出至对应的文件中。
218   ```
219
220   **使用样例2：**
221
222   ```
223   $ hitrace -b 10240 -t 10 -o /data/local/tmp/test2.ftrace app ability
224   2024/11/14 11:54:23 start to read trace.
225   2024/11/14 11:54:23 trace read done, output: /data/local/tmp/test3
226   ```
227
228   ```
229   也可根据关键词打印trace信息，使用命令`hitrace --trace_dump |grep \*\*\*`即可。
230   ```
231
2326. 开启快照模式trace采集服务。
233
234   ```
235   hitrace --start_bgsrv。
236   ```
237
238   **使用样例：**
239
240   ```
241   $ `hitrace --start_bgsrv
242   2024/11/14 11:55:53 hitrace enter, running_state is SNAPSHOT_START
243   2024/11/14 11:55:54 OpenSnapshot done.
244   ```
245
2467. 快照模式导出trace。
247
248   默认将trace信息保存至/data/log/hitrace/文件夹下，文件命名格式为`trace-YYMMDDHHmmSS@[BOOT_TIME].sys`，抓到的是二进制trace。可通过[smpartperf在线工具](https://www.smartperf.host)进行查看。
249
250   ```
251   hitrace --dump_bgsrv。
252   ```
253
254   **使用样例：**
255
256   ```
257   $ hitrace --dump_bgsrv
258   2024/11/14 12:12:56 hitrace enter, running_state is SNAPSHOT_DUMP
259   2024/11/14 12:12:57 DumpSnapshot done, output:
260       /data/log/hitrace/record_trace_20241114121257@2566589-103807063.sys
261   ```
262
2638. 关闭快照模式trace采集服务。
264
265   ```
266   hitrace --stop_bgsrv。
267   ```
268
269   **使用样例：**
270
271   ```
272   $ hitrace --stop_bgsrv
273   2024/11/14 11:59:43 hitrace enter, running_state is SNAPSHOT_STOP
274   2024/11/14 11:59:43 CloseSnapshot done.
275   ```
276
2779. 抓取trace后进行压缩。
278
279   ```
280   hitrace -z -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace。
281   ```
282
283   **使用样例：**
284
285   ```
286   $ hitrace -z -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace
287   2024/11/14 12:00:18 start capture, please wait 10s ...
288   2024/11/14 12:00:28 capture done, start to read trace.
289   2024/11/14 12:00:29 trace read done, output: /data/local/tmp/test.ftrace
290   ```
291
29210. 设置trace的输出时钟为boot(设备系统时间)。
293
294   ```
295   hitrace --trace_clock boot -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace。
296   ```
297
298   **使用样例：**
299
300   ```
301   $ hitrace --trace_clock boot -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace
302   2024/11/14 12:01:42 start capture, please wait 10s ...
303   2024/11/14 12:01:52 capture done, start to read trace.
304   2024/11/14 12:01:52 trace read done, output: /data/local/tmp/test.ftrace
305   ```
306
30711. 结束抓trace，取消trace信息打印在命令行窗口。
308
309   ```
310   hitrace --trace_finish_nodump，默认将trace信息保存至/data/log/hitrace/文件夹下。
311   ```
312
313   **使用样例：**
314
315   ```
316   $ hitrace --trace_finish_nodump
317   2024/11/14 12:03:07 hitrace enter, running_state is RECORDING_LONG_FINISH_NODUMP
318   2024/11/14 12:03:07 end capture trace.
319   ```
320