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## Environment Requirements 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 | Starts trace collection in the snapshot mode.| 27| --dump_bgsrv | Dumps the trace data in the snapshot mode to a file.| 28| --stop_bgsrv | Stops trace collection in the 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. Display the tag list in hitrace. 39 40 ``` 41 hitrace -l 42 ``` 43 44 **Example** 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. Start to capture the trace data of a specified tag. 128 129 ``` 130 hitrace --trace_begin --record app 131 ``` 132 133 **Example** 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. Stop to capture the trace data. 143 144 ``` 145 hitrace --trace_finish --record: Display the trace data in the CLI by default. 146 ``` 147 148 **Example 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: Add the output path to export the trace data to the corresponding file. 159 ``` 160 161 **Example 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. Run the **hitrace -b 10240 -t 10 -o /data/local/tmp/test2.ftrace app ability** command to capture trace data with the following settings: 170 171 ``` 172 hitrace -b 10240 -t 10 -o /data/local/tmp/test2.ftrace app ability. 173 ``` 174 175 **Example** 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 - Buffer size: 10240 KB 185 - Trace uptime: 10s 186 - Output path: **/data/local/tmp/test1.htrace** 187 - Tags: app and ability 188 1895. Dump trace information. 190 191 ``` 192 hitrace --trace_dump: Display the information in the CLI by default. 193 ``` 194 195 **Example 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: Add the output path to export the trace information to the corresponding file. 218 ``` 219 220 **Example 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 You can also run the **`hitrace --trace_dump |grep \***\***\***`** command to dump trace data based on keywords. 230 ``` 231 2326. Start trace collection in the snapshot mode. 233 234 ``` 235 hitrace --start_bgsrv 236 ``` 237 238 **Example** 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. Dump the trace data in snapshot mode. 247 248 By default, the trace data is stored in the binary format in **/data/log/hitrace/**. The file is named in the format of **trace-YYMMDDHHmmSS@[BOOT_TIME].sys**. You can view the file using [SmartPerf](https://www.smartperf.host). 249 250 ``` 251 hitrace --dump_bgsrv 252 ``` 253 254 **Example** 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. Stop trace collection in the snapshot mode. 264 265 ``` 266 hitrace --stop_bgsrv 267 ``` 268 269 **Example** 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. Compress the trace data. 278 279 ``` 280 hitrace -z -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace 281 ``` 282 283 **Example** 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. Set the trace output clock to **boot** (system time of the device). 293 294 ``` 295 hitrace --trace_clock boot -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace 296 ``` 297 298 **Example** 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. Stop capturing and printing trace data in the CLI. 308 309 ``` 310 hitrace --trace_finish_nodump: Saves the trace data to the /data/log/hitrace/ directory by default. 311 ``` 312 313 **Example** 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