1# Viewing HiTraceMeter Logs 2 3<!--Kit: Performance Analysis Kit--> 4<!--Subsystem: HiviewDFX--> 5<!--Owner: @qq_437963121--> 6<!--Designer: @MontSaintMichel--> 7<!--Tester: @gcw_KuLfPSbe--> 8<!--Adviser: @foryourself--> 9 10## Viewing Logs on DevEco Studio 11 12In DevEco Studio Profiler, you can display HiTraceMeter logs to analyze the CPU usage and thread running status of applications and services and view the CPU consumption in a specified period. For details, see [CPU Activity Analysis: CPU](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/ide-insight-session-cpu). 13 14 15## Viewing Logs Using Command Line Tools 16 171. Set up the environment for OpenHarmony Device Connector (hdc). For details, see [Environment Setup](hdc.md#environment-setup). 18 192. In the **Terminal** window of DevEco Studio or the CLI on the host, run the **hdc shell** command to connect to the device, and run the [HiTrace](hitrace.md) command on the device to enable the HiTraceMeter logging service. 20 21 ```shell 22 PS D:\xxx\xxx> hdc shell 23 $ hitrace --trace_begin app 24 ``` 25 263. Run the program that enables the HiTraceMeter logging on the device. 27 284. Use HiTrace to collect trace information in text format and save the trace file to the **/data/local/tmp/** directory of the device. For details, see [Capturing Text Trace Data in Snapshot Mode](hitrace.md#capturing-text-trace-data-in-snapshot-mode). 29 305. Exit the device, enter the host, and export the HiTraceMeter text logs to the current directory. (Change the file name **trace.ftrace** in the following command based on the file name set during collection.) 31 32 ```shell 33 $ exit 34 PS D:\xxx\xxx> hdc file recv /data/local/tmp/trace.ftrace ./ 35 ``` 36 376. You can search for keywords such as the logging name in the HiTraceMeter logs to check whether the logging is successful. 38 397. Display and analyze the HiTraceMeter text file. 40 41 - Import the log file to DevEco Studio for analysis. 42 43 In DevEco Studio Profiler, select **Open File** to import the HiTraceMeter log file. 44 45 For details, see [CPU Activity Analysis: CPU](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/ide-insight-session-cpu). 46 - Use [Smartperf_Host](https://gitee.com/openharmony/developtools_smartperf_host) for analysis. You can download the tool from [developtools_smartperf_host Release](https://gitee.com/openharmony/developtools_smartperf_host/releases). 47 48 49## User-Mode Trace Format 50 51 52### User-Mode Trace Format Before API version 19 53 54| Trace Type| Format When HiTraceChain is Enabled| Format When HiTraceChain is Disabled| 55| -------- | -------- | -------- | 56| Start a synchronous trace logging| B\|PID\|H:[ChainId,SpanId,ParentSpanId]\#name | B\|PID\|H:name | 57| Stop a synchronous trace logging| E\|PID\| | E\|PID\| | 58| Start an asynchronous trace logging| S\|PID\|H:[ChainId,SpanId,ParentSpanId]\#name taskId | S\|PID\|H:name taskId | 59| Stop an asynchronous trace logging| F\|PID\|H:[ChainId,SpanId,ParentSpanId]\#name taskId | F\|PID\|H:name taskId | 60| Log an integer trace| C\|PID\|H:[ChainId,SpanId,ParentSpanId]\#name count | C\|PID\|H:name count | 61 62> **NOTE** 63> 64> The maximum length of a user-mode trace is 512 characters. Excess characters will be truncated. 65 66 67**Fields** 68 69 70- **B/E/S/F/C** 71 72 - **B**: Starts a synchronous trace logging. 73 - **E**: Stops a synchronous trace logging. 74 - **S**: Starts an asynchronous trace logging. 75 - **F**: Stops an asynchronous trace logging. 76 - **C**: Logs an integer trace. 77 78- **PID** 79 80 Process ID. 81 82- **[ChainId,SpanId,ParentSpanId]\#** 83 84 When HiTraceChain is enabled, **HiTraceId** is recorded in the trace logging and separated from the **name** field using the hashtag (\#). 85 86 When HiTraceChain is not enabled, this field is not included in the trace logs. 87 88 - **ChainId**: Chain ID of **HiTraceId**. 89 - **SpanId**: Span ID of **HiTraceId**. 90 - **ParentSpanId**: Parent span ID of **HiTraceId**. 91 92- **name** 93 94 Logging name or integer variable name. 95 96- **taskId** 97 98 Asynchronous trace ID, which is used together with the **name** field to match the start and stop of an asynchronous trace logging. 99 100 Use a space to separate **taskId** and **name**. 101 102- **count** 103 104 Integer value. 105 106 Use a space to separate **count** and **name**. 107 108 109### User-Mode Trace Format Since API Version 19 110 111Vertical bars (|) are used as separators for fields. For subsequent new fields, use the **| + Field** format to add them to the end of the current user-mode trace format. 112 113| Trace Type| Format When HiTraceChain is Enabled| Format When HiTraceChain is Disabled| 114| -------- | -------- | -------- | 115| Start a synchronous trace logging| B\|PID\|H:[ChainId,SpanId,ParentSpanId]\#name\|%level%tag\|customArgs | B\|PID\|H:name\|%level%tag\|customArgs | 116| Stop a synchronous trace logging| E\|PID\|%level%tag | E\|PID\|%level%tag | 117| Start an asynchronous trace logging| S\|PID\|H:[ChainId,SpanId,ParentSpanId]\#name\|taskId\|%level%tag\|customCategory\|customArgs | S\|PID\|H:name\|taskId\|%level%tag\|customCategory\|customArgs | 118| Stop an asynchronous trace logging| F\|PID\|H:[ChainId,SpanId,ParentSpanId]\#name\|taskId\|%level%tag | F\|PID\|H:name\|taskId\|%level%tag | 119| Log an integer trace| C\|PID\|H:[ChainId,SpanId,ParentSpanId]\#name\|count\|%level%tag | C\|PID\|H:name\|count\|%level%tag | 120 121> **NOTE** 122> 123> The maximum length of a user-mode trace is 512 characters. It is recommended that the total length of **name**, **customCategory**, and **customArgs** be less than or equal to 420 characters to avoid truncation. 124 125 126**Fields** 127 128 129- **B/E/S/F/C** 130 131 - **B**: Starts a synchronous trace logging. 132 - **E**: Stops a synchronous trace logging. 133 - **S**: Starts an asynchronous trace logging. 134 - **F**: Stops an asynchronous trace logging. 135 - **C**: Logs an integer trace. 136 137- **PID** 138 139 Process ID. 140 141- **[ChainId,SpanId,ParentSpanId]\#** 142 143 When HiTraceChain is enabled, **HiTraceId** is recorded in the trace logging and separated from the **name** field using the hashtag (\#). 144 145 When HiTraceChain is not enabled, this field is not included in the trace logs. 146 147 - **ChainId**: Chain ID of **HiTraceId**. 148 - **SpanId**: Span ID of **HiTraceId**. 149 - **ParentSpanId**: Parent span ID of **HiTraceId**. 150 151- **name** 152 153 Logging name or integer variable name. 154 155- **taskId** 156 157 Asynchronous trace ID, which is used together with the **name** field to match the start and stop of an asynchronous trace logging. 158 159- **count** 160 161 Integer value. 162 163- **%level** 164 165 The **level** field passed through the logging API, indicating the logging level. The value can be **D**, **I**, **C**, or **M**. 166 167 For the mapping between the **level** field and **%level**, see [HiTraceOutputLevel](#hitraceoutputlevel). 168 169 > **NOTE** 170 > 171 > Before API version 19, the trace logging API does not have the **level** field. By default, the trace logging level is **COMMERCIAL**. 172 173- **%tag** 174 175 Tag type of the trace logging, which is represented by a two-digit number. The value can contain multiple two-digit numbers in ascending order. For example, **B|1314|H:TestFunction|I3062** indicates that the trace logging belongs to the **HITRACE_TAG_OHOS** and **HITRACE_TAG_APP** tags. 176 177 For details about the mapping between tag names, tag values, and **%tag**, see [HiTraceMeter Tags](#hitracemeter-tags). 178 179 > **NOTE** 180 > 181 > The NDK C/C++ and ArkTs/JS HiTraceMeter performance logging APIs do not have fields corresponding to **%tag**. They are application logging APIs, whose tag name is **HITRACE_TAG_APP** and the corresponding **%tag** value in the user-mode trace is **62**. 182 183- **customCategory** 184 185 Custom category name. 186 187 In the trace analysis tool, asynchronous traces with the same category name in the same process are displayed in the same lane. 188 189- **customArgs** 190 191 Custom key-value pair, in the format of **key=value**. Multiple key-value pairs are separated by commas (,), for example, **key1=value1,key2=value2**. 192 193 In the trace analysis tool, the parsing results of **customArgs** that meet the format requirements are displayed in key-value pairs. 194 195 196**NOTE** 197 198 199In practice, if the **customCategory** and **customArgs** fields are not required, pass empty strings. (The two fields are involved only in the APIs for starting the synchronous trace logging and asynchronous trace logging.) 200 201 202The following describes whether the two fields are empty strings in the user-mode trace format when HiTraceChain is disabled. For details about how to use HiTraceChain, see [Using HiTraceChain](hitracechain-intro.md). 203 204 205In trace logging APIs earlier than API version 19, the two fields are considered as empty strings by default. 206 207 208- Synchronous trace logging start API 209 210 - **customArgs** is not an empty string. 211 212 ```text 213 B|PID|H:name|%level%tag|customArgs 214 ``` 215 216 - **customArgs** is an empty string. 217 218 ```text 219 B|PID|H:name|%level%tag 220 ``` 221 222- Asynchronous trace logging start API 223 224 - **customCategory** and **customArgs** are not empty strings. 225 226 ```text 227 S|PID|H:name|taskId|%level%tag|customCategory|customArgs 228 ``` 229 230 - **customCategory** is an empty string, and **customArgs** is not an empty string. 231 232 ```text 233 S|PID|H:name|taskId|%level%tag||customArgs 234 ``` 235 236 - **customCategory** is not an empty string, and **customArgs** is an empty string. 237 238 ```text 239 S|PID|H:name|taskId|%level%tag|customCategory 240 ``` 241 242 - **customCategory** and **customArgs** are both empty strings. 243 244 ```text 245 S|PID|H:name|taskId|%level%tag 246 ``` 247 248 249### HiTraceMeter Tags 250 251| Name| Value| %tag | 252| -------- | -------- | -------- | 253| HITRACE_TAG_ALWAYS | 1ULL << 0 | 00 | 254| HITRACE_TAG_COMMERCIAL | 1ULL << 5 | 05 | 255| HITRACE_TAG_DRM | 1ULL << 6 | 06 | 256| HITRACE_TAG_SECURITY | 1ULL << 7 | 07 | 257| HITRACE_TAG_ANIMATION | 1ULL << 9 | 09 | 258| HITRACE_TAG_PUSH | 1ULL << 10 | 10 | 259| HITRACE_TAG_VIRSE | 1ULL << 11 | 11 | 260| HITRACE_TAG_MUSL | 1ULL << 12 | 12 | 261| HITRACE_TAG_FFRT | 1ULL << 13 | 13 | 262| HITRACE_TAG_CLOUD | 1ULL << 14 | 14 | 263| HITRACE_TAG_DEV_AUTH | 1ULL << 15 | 15 | 264| HITRACE_TAG_COMMONLIBRARY | 1ULL << 16 | 16 | 265| HITRACE_TAG_HDCD | 1ULL << 17 | 17 | 266| HITRACE_TAG_HDF | 1ULL << 18 | 18 | 267| HITRACE_TAG_USB | 1ULL << 19 | 19 | 268| HITRACE_TAG_INTERCONNECTION | 1ULL << 20 | 20 | 269| HITRACE_TAG_DLP_CREDENTIAL | 1ULL << 21 | 21 | 270| HITRACE_TAG_ACCESS_CONTROL | 1ULL << 22 | 22 | 271| HITRACE_TAG_NET | 1ULL << 23 | 23 | 272| HITRACE_TAG_NWEB | 1ULL << 24 | 24 | 273| HITRACE_TAG_HUKS | 1ULL << 25 | 25 | 274| HITRACE_TAG_USERIAM | 1ULL << 26 | 26 | 275| HITRACE_TAG_DISTRIBUTED_AUDIO | 1ULL << 27 | 27 | 276| HITRACE_TAG_DLSM | 1ULL << 28 | 28 | 277| HITRACE_TAG_FILEMANAGEMENT | 1ULL << 29 | 29 | 278| HITRACE_TAG_OHOS | 1ULL << 30 | 30 | 279| HITRACE_TAG_ABILITY_MANAGER | 1ULL << 31 | 31 | 280| HITRACE_TAG_ZCAMERA | 1ULL << 32 | 32 | 281| HITRACE_TAG_ZMEDIA | 1ULL << 33 | 33 | 282| HITRACE_TAG_ZIMAGE | 1ULL << 34 | 34 | 283| HITRACE_TAG_ZAUDIO | 1ULL << 35 | 35 | 284| HITRACE_TAG_DISTRIBUTEDDATA | 1ULL << 36 | 36 | 285| HITRACE_TAG_MDFS | 1ULL << 37 | 37 | 286| HITRACE_TAG_GRAPHIC_AGP | 1ULL << 38 | 38 | 287| HITRACE_TAG_ACE | 1ULL << 39 | 39 | 288| HITRACE_TAG_NOTIFICATION | 1ULL << 40 | 40 | 289| HITRACE_TAG_MISC | 1ULL << 41 | 41 | 290| HITRACE_TAG_MULTIMODALINPUT | 1ULL << 42 | 42 | 291| HITRACE_TAG_SENSORS | 1ULL << 43 | 43 | 292| HITRACE_TAG_MSDP | 1ULL << 44 | 44 | 293| HITRACE_TAG_DSOFTBUS | 1ULL << 45 | 45 | 294| HITRACE_TAG_RPC | 1ULL << 46 | 46 | 295| HITRACE_TAG_ARK | 1ULL << 47 | 47 | 296| HITRACE_TAG_WINDOW_MANAGER | 1ULL << 48 | 48 | 297| HITRACE_TAG_ACCOUNT_MANAGER | 1ULL << 49 | 49 | 298| HITRACE_TAG_DISTRIBUTED_SCREEN | 1ULL << 50 | 50 | 299| HITRACE_TAG_DISTRIBUTED_CAMERA | 1ULL << 51 | 51 | 300| HITRACE_TAG_DISTRIBUTED_HARDWARE_FWK | 1ULL << 52 | 52 | 301| HITRACE_TAG_GLOBAL_RESMGR | 1ULL << 53 | 53 | 302| HITRACE_TAG_DEVICE_MANAGER | 1ULL << 54 | 54 | 303| HITRACE_TAG_SAMGR | 1ULL << 55 | 55 | 304| HITRACE_TAG_POWER | 1ULL << 56 | 56 | 305| HITRACE_TAG_DISTRIBUTED_SCHEDULE | 1ULL << 57 | 57 | 306| HITRACE_TAG_DEVICE_PROFILE | 1ULL << 58 | 58 | 307| HITRACE_TAG_DISTRIBUTED_INPUT | 1ULL << 59 | 59 | 308| HITRACE_TAG_BLUETOOTH | 1ULL << 60 | 60 | 309| HITRACE_TAG_ACCESSIBILITY_MANAGER | 1ULL << 61 | 61 | 310| HITRACE_TAG_APP | 1ULL << 62 | 62 | 311 312 313### HiTraceOutputLevel 314 315| Enum Name (C/C++)| Enum Name (ArkTS/JS)| Value| %level | 316| -------- | -------- | -------- | -------- | 317| HITRACE_LEVEL_DEBUG | DEBUG | 0 | D | 318| HITRACE_LEVEL_INFO | INFO | 1 | I | 319| HITRACE_LEVEL_CRITICAL | CRITICAL | 2 | C | 320| HITRACE_LEVEL_COMMERCIAL | COMMERCIAL | 3 | M | 321| HITRACE_LEVEL_MAX | MAX | 3 | M | 322