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- The devices are properly connected. 9 10## Command Description 11 12| Command | Description | 13| --------------------- | ------------------------------------------------------------ | 14| -h | Displays help information. | 15| -l | Displays the tag list. | 16| --trace_begin | Starts capturing trace data. | 17| --trace_finish | Stops capturing trace data. | 18| --trace_dump | Dumps trace information. | 19| -b N | Sets the buffer size (in KB) for trace data. The default buffer size is 2048 KB.| 20| -t N | Sets the trace uptime in seconds, which depends on the time required for analysis. The default value is 5 seconds.| 21| -o | Specifies the target file name (**stdout** by default). | 22| -z | Compresses the trace data. | 23| --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**.| 24| --trace_finish_nodump | Stops printing when trace capturing is stopped. | 25| --start_bgsrv | Starts trace collection in the snapshot mode. | 26| --dump_bgsrv | Dumps the trace data in the snapshot mode to a file. | 27| --stop_bgsrv | Stops trace collection in the snapshot mode. | 28| --trace_level | Sets the trace level threshold. The trace level lower than the threshold does not take effect. The value can be **Debug**, **Info**, **Critical**, **Commercial**, or **D**, **I**, **C**, or **M**. The logging level priority is **D** < **I** < **C** < **M**. You can use the logging APIs with the trace level in [js-apis-hitracemeter](../reference/apis-performance-analysis-kit/js-apis-hitracemeter.md) and [_hitrace](../reference/apis-performance-analysis-kit/_hitrace.md) to check whether the trace output of different thresholds meets the expectation.| 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 ```shell 41 hitrace -l 42 ``` 43 **Example** 44 45 ```shell 46 $ hitrace -l 47 2024/11/14 11:43:00 hitrace enter, running_state is SHOW_LIST_CATEGORY 48 tagName: description: 49 ability - Ability Manager 50 accesscontrol - Access Control Module 51 account - Account Manager 52 ace - ACE development framework 53 animation - Animation 54 app - APP Module 55 ark - ARK Module 56 bluetooth - communicatio bluetooth 57 cloud - Cloud subsystem tag 58 cloudfile - Cloud file system 59 commercial - Commercial version tag 60 commonlibrary - commonlibrary subsystem 61 daudio - Distributed Audio 62 dcamera - Distributed Camera 63 deviceauth - Device Auth 64 devicemanager - Device Manager 65 deviceprofile - Device Profile 66 dhfwk - Distributed Hardware FWK 67 dinput - Distributed Input 68 disk - Disk I/O 69 istributeddatamgr - Distributed Data Manager 70 dlpcre - Dlp Credential Service 71 drm - Digital Rights Management 72 dsched - Distributed Schedule 73 dscreen - Distributed Screen 74 dslm - device security level 75 dsoftbus - Distributed Softbus 76 ffrt - ffrt tasks 77 filemanagement - filemanagement 78 freq - CPU Frequency 79 graphic - Graphic Module 80 gresource - Global Resource Manager 81 hdcd - hdcd 82 hdf - hdf subsystem 83 huks - Universal KeyStore 84 i2c - I2C Events 85 idle - CPU Idle 86 interconn - Interconnection subsystem 87 ipa - thermal power allocator 88 irq - IRQ Events 89 irqoff - IRQ-disabled code section tracing 90 load - CPU Load 91 mdfs - Mobile Distributed File System 92 membus - Memory Bus Utilization 93 memory - Memory 94 memreclaim - Kernel Memory Reclaim 95 misc - Misc Module 96 mmc - eMMC commands 97 msdp - Multimodal Sensor Data Platform 98 multimodalinput - HITRACE_TAG_MULTIMODALINPUT 99 net - net 100 notification - Notification Module 101 nweb - NWEB Module 102 ohos - OpenHarmony 103 pagecache - Page cache 104 power - Power Manager 105 preemptoff - Preempt-disabled code section tracing 106 push - Push subsystem 107 regulators - Voltage and Current Regulators 108 rpc - RPC and IPC 109 samgr - samgr 110 sched - CPU Scheduling 111 security - Security subsystem 112 sensors - Sensors Module 113 sync - Synchronization 114 ufs - UFS commands 115 usb - usb subsystem 116 useriam - useriam 117 virse - Virtualization Service 118 window - Window Manager 119 workq - Kernel Workqueues 120 zaudio - OpenHarmony Audio Module 121 zcamera - OpenHarmony Camera Module 122 zimage - OpenHarmony Image Module 123 zmedia - OpenHarmony Media Module 124 ``` 1252. Start to capture the trace data of a specified tag. 126 127 ```shell 128 hitrace --trace_begin --record app 129 ``` 130 **Example** 131 132 ```shell 133 $ hitrace --trace_begin --record app 134 2024/11/14 11:48:45 hitrace enter, running_state is RECORDING_LONG_BEGIN_RECORD 135 2024/11/14 11:48:45 args: tags:app bufferSize:18432 overwrite:1 136 2024/11/14 11:48:45 OpenRecording done. 137 ``` 1383. Stop to capture the trace data. 139 140 By default, the trace data is displayed in the CLI. 141 142 ```shell 143 hitrace --trace_finish --record 144 ``` 145 **Example 1** 146 147 ```shell 148 $ hitrace --trace_finish --record 149 2024/11/14 11:50:33 hitrace enter, running_state is RECORDING_LONG_FINISH_RECORD 150 2024/11/14 11:50:33 capture done, output files: 151 /data/log/hitrace/record_trace_20241114115033@3010728-656499531.sys 152 ``` 153 Add the output path to export the trace data to the corresponding file. 154 155 ```shell 156 hitrace --trace_finish -o /data/local/tmp/test.ftrace 157 ``` 158 **Example 2** 159 160 ```shell 161 $ hitrace --trace_finish -o /data/local/tmp/test.ftrace 162 2024/11/14 11:50:33 start to read trace. 163 2024/11/14 11:50:33 trace read done, output: /data/local/tmp/test.ftrace 164 ``` 1654. Capture trace data with the following settings: 166 167 ```shell 168 hitrace -b 10240 -t 10 -o /data/local/tmp/test2.ftrace app ability 169 ``` 170 **Example** 171 172 ```shell 173 $ hitrace -b 10240 -t 10 -o /data/local/tmp/test2.ftrace app ability 174 2024/11/14 11:52:13 start capture, please wait 10s ... 175 2024/11/14 11:52:23 capture done, start to read trace. 176 2024/11/14 11:52:23 trace read done, output: /data/local/tmp/test2.ftrace 177 ``` 178 - Buffer size: 10240 KB 179 - Trace uptime: 10s 180 - Output path: **/data/local/tmp/test2.ftrace**. 181 - Tags: app and ability 1825. Dump trace information. 183 184 By default, the trace data is displayed in the CLI. 185 186 ```shell 187 hitrace --trace_dump 188 ``` 189 **Example 1** 190 191 ```shell 192 $ hitrace --trace_dump 193 2024/11/14 11:54:23 start to read trace. 194 # tracer: nop 195 # 196 # entries-in-buffer/entries-written: 2/2 #P:4 197 # 198 # _-----=> irqs-off 199 # / _----=> need-resched 200 # | / _---=> hardirq/softirq 201 # || / _--=> preempt-depth 202 # ||| / delay 203 # TASK-PID TGID CPU# |||| TIMESTAMP FUNCTION 204 # | | | | |||| | | 205 <...>-21829 ( 19280) [003] .... 3011033.731844: tracing_mark_write: trace_event_clock_sync: realtime_ts=1732002022239 206 <...>-21829 ( 19280) [003] .... 3011033.731865: tracing_mark_write: trace_event_clock_sync: parent_ts=3011033.750000 207 # 208 ``` 209 Add the output path to export the trace data to the corresponding file. 210 211 ```shell 212 hitrace --trace_dump -o /data/local/tmp/test3.ftrace 213 ``` 214 **Example 2** 215 216 ```shell 217 $ hitrace --trace_dump -o /data/local/tmp/test3.ftrace 218 2024/11/14 11:54:23 start to read trace. 219 2024/11/14 11:54:23 trace read done, output: /data/local/tmp/test3.ftrace 220 ``` 221 You can also run the **hitrace --trace_dump | grep xxx** command to dump trace data based on keywords. 2226. Start trace collection in the snapshot mode. 223 224 ```shell 225 hitrace --start_bgsrv 226 ``` 227 **Example** 228 229 ```shell 230 $ hitrace --start_bgsrv 231 2024/11/14 11:55:53 hitrace enter, running_state is SNAPSHOT_START 232 2024/11/14 11:55:54 OpenSnapshot done. 233 ``` 2347. Dump the trace data in snapshot mode. 235 236 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). 237 238 ```shell 239 hitrace --dump_bgsrv 240 ``` 241 **Example** 242 243 ```shell 244 $ hitrace --dump_bgsrv 245 2024/11/14 12:12:56 hitrace enter, running_state is SNAPSHOT_DUMP 246 2024/11/14 12:12:57 DumpSnapshot done, output: 247 /data/log/hitrace/record_trace_20241114121257@2566589-103807063.sys 248 ``` 2498. Stop trace collection in the snapshot mode. 250 251 ```shell 252 hitrace --stop_bgsrv 253 ``` 254 **Example** 255 256 ```shell 257 $ hitrace --stop_bgsrv 258 2024/11/14 11:59:43 hitrace enter, running_state is SNAPSHOT_STOP 259 2024/11/14 11:59:43 CloseSnapshot done. 260 ``` 2619. Compress the trace data. 262 263 ```shell 264 hitrace -z -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace 265 ``` 266 **Example** 267 268 ```shell 269 $ hitrace -z -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace 270 2024/11/14 12:00:18 start capture, please wait 10s ... 271 2024/11/14 12:00:28 capture done, start to read trace. 272 2024/11/14 12:00:29 trace read done, output: /data/local/tmp/test.ftrace 273 ``` 27410. Set the trace output clock to **boot** (system time of the device). 275 276 ```shell 277 hitrace --trace_clock boot -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace 278 ``` 279 **Example** 280 281 ```shell 282 $ hitrace --trace_clock boot -b 102400 -t 10 sched freq idle disk -o /data/local/tmp/test.ftrace 283 2024/11/14 12:01:42 start capture, please wait 10s ... 284 2024/11/14 12:01:52 capture done, start to read trace. 285 2024/11/14 12:01:52 trace read done, output: /data/local/tmp/test.ftrace 286 ``` 28711. Stop capturing and printing trace data in the CLI. 288 289 By default, the trace data is saved in **/data/log/hitrace/**. 290 291 ```shell 292 hitrace --trace_finish_nodump 293 ``` 294 **Example** 295 296 ```shell 297 $ hitrace --trace_finish_nodump 298 2024/11/14 12:03:07 hitrace enter, running_state is RECORDING_LONG_FINISH_NODUMP 299 2024/11/14 12:03:07 end capture trace. 300 ``` 30112. Set the trace level threshold to **Info**. 302 303 ```shell 304 hitrace --trace_level Info 305 ``` 306 **Example** 307 308 ```shell 309 $ hitrace --trace_level Info 310 2024/11/14 12:05:07 hitrace enter, running_state is SET_TRACE_LEVEL 311 2024/11/14 12:05:07 success to set trace level. 312 ``` 313 314<!--no_check-->