Viewing HiTraceMeter Logs

Viewing Logs on DevEco Studio

In 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.

Viewing Logs Using Command Line Tools

1. Set up the environment for OpenHarmony Device Connector (hdc). For details, see Environment Setup.

2. 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 command on the device to enable the HiTraceMeter logging service.

   PS D:\xxx\xxx> hdc shell
   $ hitrace --trace_begin app
   

3. Run the program that enables the HiTraceMeter logging on the device.

4. 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.

5. 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.)

   $ exit
   PS D:\xxx\xxx> hdc file recv /data/local/tmp/trace.ftrace ./
   

6. You can search for keywords such as the logging name in the HiTraceMeter logs to check whether the logging is successful.

7. Display and analyze the HiTraceMeter text file.

   • Import the log file to DevEco Studio for analysis.

     In DevEco Studio Profiler, select Open File to import the HiTraceMeter log file.

     For details, see CPU Activity Analysis.

   • Use the Smartperf_Host tool for analysis.

User-Mode Trace Format

You can run the hitrace command to collect user-mode trace logs generated by the HiTraceMeter API to analyze application performance. The following describes the format and extension rule for user-mode traces of the synchronous, asynchronous, and integer value types, including the field composition, description, and relationship between fields and input parameters, as well as sample trace logs in different scenarios for reference.

For details about the user-mode trace format since API version 19, see User-mode Trace Format Since API Version 19. For details about the user-mode trace format in versions earlier than API version 19, see User-mode Trace Format Before API Version 19.

User-mode Trace Format Since API Version 19

Synchronous trace

• Start trace: [Type identifier]|[Process ID]|H:[ID of the distributed call chain tracing task]#[Content]|[Level and tag set]|[Custom key-value pair]

• End trace: [Type identifier]|[Process ID]|[Level and tag set]

A synchronous trace consists of a start trace (Type identifier: B) and an end trace (Type identifier: E).

Asynchronous trace

• Start trace: [Type identifier]|[Process ID]|H:[ID of the distributed call chain tracing task]#[Content]|[Asynchronous task ID]|[Level and tag set]|[Custom category name]|[Custom key-value pair]

• End trace: [Type identifier]|[Process ID]|H:[ID of the distributed call chain tracing task]#[Content]|[Asynchronous task ID]|[Level and tag set]

An asynchronous trace consists of a start trace (Type identifier: S) and an end trace (Type identifier: F).

Integer value trace

• Trace format: [Type identifier]|[Process ID]|H:[ID of the distributed call chain tracing task]#[Content]|[Integer value]|[Level and tag set]

An integer value trace contains only one independent trace whose type identifier is C.

NOTE

1. A valid and complete synchronous trace or asynchronous trace contains a start trace and an end trace. You need to ensure that the API calls match. Otherwise, the performance trace may be abnormal. For details, see @ohos.hiTraceMeter (Performance Tracing) or C++ APIs in trace.h.
2. The maximum length of a user-mode trace is 512 characters. Excess characters will be truncated.

Fields

The following describes fields of the user-mode trace, including the field composition, description, and relationship between fields and logging input parameters. For details, see @ohos.hiTraceMeter (Performance Tracing).

• Type identifiers

  The type identifier is associated with the called @ohos.hiTraceMeter (Performance Tracing) API. The mappings are as follows:

  • B: Identifies the start of a synchronous time slice trace.
  • E: Identifies the end of a synchronous time slice trace.
  • S: Identifies the start of an asynchronous time slice trace.
  • F: Identifies the end of an asynchronous time slice trace.
  • C: Identifies the integer trace event.

• IDs of distributed call chain tracing tasks

  When HiTraceChain (Distributed Tracing) is enabled, the HiTraceId information is recorded in the trace logs in the format of [ChainId,SpanId,ParentSpanId]. The HiTraceId information is separated from the content field by the hash (#) separator.

  When HiTraceChain (Distributed Tracing) is not enabled, this field is not included in the trace logs.

  • ChainId: Trace chain ID of HiTraceId.
  • SpanId: Span ID of HiTraceId.
  • ParentSpanId: Parent span ID of HiTraceId.

  For details about how to use HiTraceChain, see Using HiTraceChain (ArkTS) and Using HiTraceChain (C/C++).

• Content

  This field indicates the name of a trace task or an integer variable. It corresponds to the name parameter of the @ohos.hiTraceMeter (Performance Tracing) API.

• Asynchronous task IDs

  This field and the content field are used to match the start and end of the same asynchronous trace. It corresponds to the taskId parameter in the @ohos.hiTraceMeter (Performance Tracing) API.

• Integer values

  This field is the value of the integer variable to trace and is contained only in the integer value trace task. It corresponds to count parameter in the @ohos.hiTraceMeter (Performance Tracing) API.

• Levels and tag sets

  This field consists of the level and tag.

  The level is passed through the logging API, whose value can be D, I, C, or M. It corresponds to the level parameter in the @ohos.hiTraceMeter (Performance Tracing) API. For details about the description and mappings, seeHiTraceOutputLevel.

  The tag set indicates the tags of the trace, each of which is represented by a two-digit number. The tag set can contain multiple two-digit numbers in ascending order.

  For example, in B|1314|H:TestFunction|I3062, I indicates that the logging level is Info, and 3062 indicates the tag set of the logging trace. According to the mappings between tag names and values, 30 corresponds to the ohos tag, and 62 corresponds to the app tag. For details, see HiTraceMeter Tags.

  NOTE

  1. Since API version 19, the output level can be customized. In versions earlier than API version 19, the output level is COMMERCIAL by default.

  2. The system user-mode trace may have multiple tags. However, the tag set cannot be specified in the application user-mode trace APIs provided by @ohos.hiTraceMeter (Performance Tracing) and trace.h. The tag of the application user-mode trace is app and its value is 62.

• Custom category names

  This field can be used for custom trace collection. It corresponds to the customCategory parameter in the @ohos.hiTraceMeter (Performance Tracing) API. The value of this field may be empty, which changes the log format. For details, see Empty Field Scenarios.

  In the trace analysis tool, asynchronous traces with the same category name in the same process are displayed in the same lane.

• Custom key-value pairs

  This field is in the format of key=value. Multiple key-value pairs are separated by commas (,), for example, key1=value1,key2=value2. It corresponds to the customArgs parameter of the @ohos.hiTraceMeter (Performance Tracing) API. The value of this field may be empty, which changes the log format. For details, see Empty Field Scenarios.

  In the trace analysis tool, the parsing results of custom key-value pairs that meet the format requirements are displayed in key-value pairs.

Field Extension Rules

Since API version 19, new fields are added to the end of the current user-mode trace format in the format of |field.

Sample Trace Logs in Different Scenarios

Trace Type	Format When HiTraceChain is Enabled	Format When HiTraceChain is Disabled
Start a synchronous trace logging	B|1234|H:[a92ab94c18e1341,0,0]#tracename|M62|user=root,type=2	B|1234|H:tracename|M62|user=root,type=2
Stop a synchronous trace logging	E|1234|M62	E|1234|M62
Start an asynchronous trace logging	S|1234|H:[a92ab94c18e1341,0,0]#tracename|428|M62|appcategory01|user=root,type=2	S|1234|H:tracename|428|M62|appcategory01|user=root,type=2
Stop an asynchronous trace logging	F|1234|H:[a92ab94c18e1341,0,0]#tracename|428|M62	F|1234|H:tracename|428|M62
Log an integer trace	C|1234|H:[a92ab94c18e1341,0,0]#tracename|5678|M62	C|1234|H:tracename|5678|M62

In the preceding samples, the process ID is 1234, the content is tracename, the level is M, indicating the COMMERCIAL level, and the tag set is 62, corresponding to the app tag. When HiTraceChain is enabled, the ID of the distributed call chain trace task is [a92ab94c18e1341,0,0]. The custom key-value pairs of synchronous and asynchronous traces are both user=root,type=2. The asynchronous task ID is 428, and the custom category name is appcategory01. The value of the integer variable to trace is 5678.

NOTE

The maximum length of a user-mode trace is 512 characters. Excess characters will be truncated. Therefore, it is recommended that the total length of the tracename, customCategory, and customArgs fields be less than or equal to 420 characters.

Empty Field Scenarios

In the user-mode trace, if the middle field is empty, the vertical bar (|) is retained. If the last field is empty, the vertical bar (|) is removed. The following shows examples of the customCategory and customArgs parameters of the hiTraceMeter.startAsyncTrace() and hiTraceMeter.startSyncTrace() APIs.

• Start a synchronous trace logging

  • The value of customArgs is not empty:

    B|[Process ID]|H:[ID of the distributed call chain tracing task]#[Content]|[Level and tag set]|[Custom key-value pair]
    

  • The value of customArgs is empty:

    B|[Process ID]|H:[ID of the distributed call chain tracing task]#[Content]|[Level and tag set]
    

• Start an asynchronous trace logging

  • The values of customCategory and customArgs are not empty:

    S|[Process ID]|H:[ID of the distributed call chain tracing task]#[Content]|[Asynchronous task ID]|[Level and tag set]|[Custom category name]|[Custom key-value pair]
    

  • The value of customCategory is empty while the value of customArgs is not empty:

    S|[Process ID]|H:[ID of the distributed call chain tracing task]#[Content]|[Asynchronous task ID]|[Level and tag set]||[Custom key-value pair]
    

  • The value of customCategory is not empty while the value of customArgs is empty:

    S|[Process ID]|H:[ID of the distributed call chain tracing task]#[Content]|[Asynchronous task ID]|[Level and tag set]|[Custom category name]
    

  • The values of customCategory and customArgs are empty:

    S|[Process ID]|H:[ID of the distributed call chain tracing task]#[Content]|[Asynchronous task ID]|[Level and tag set]
    

HiTraceMeter Tags

The following shows the user-mode tag set of HiTraceMeter. The tag values are the left shift values based on the digit 1 at the actual code layer. You can use hitrace to obtain the description of the user-mode tag. always is the default enabled system tag and commercial is the custom tag for the commercial version.

Name	Constant Value at the Code Layer	Value
always	1ULL << 0	00
commercial	1ULL << 5	05
drm	1ULL << 6	06
security	1ULL << 7	07
animation	1ULL << 9	09
push	1ULL << 10	10
virse	1ULL << 11	11
ffrt	1ULL << 13	13
musl	1ULL << 12	12
cloud	1ULL << 14	14
deviceauth	1ULL << 15	15
commonlibrary	1ULL << 16	16
hdcd	1ULL << 17	17
hdf	1ULL << 18	18
usb	1ULL << 19	19
interconn	1ULL << 20	20
dlpcre	1ULL << 21	21
accesscontrol	1ULL << 22	22
net	1ULL << 23	23
nweb	1ULL << 24	24
huks	1ULL << 25	25
useriam	1ULL << 26	26
daudio	1ULL << 27	27
dlsm	1ULL << 28	28
filemanagement	1ULL << 29	29
ohos	1ULL << 30	30
ability	1ULL << 31	31
zcamera	1ULL << 32	32
zmedia	1ULL << 33	33
zimage	1ULL << 34	34
zaudio	1ULL << 35	35
distributeddatamgr	1ULL << 36	36
mdfs	1ULL << 37	37
graphic	1ULL << 38	38
ace	1ULL << 39	39
notification	1ULL << 40	40
misc	1ULL << 41	41
multimodalinput	1ULL << 42	42
sensors	1ULL << 43	43
msdp	1ULL << 44	44
dsoftbus	1ULL << 45	45
rpc	1ULL << 46	46
ark	1ULL << 47	47
window	1ULL << 48	48
account	1ULL << 49	49
dscreen	1ULL << 50	50
dcamera	1ULL << 51	51
dhfwk	1ULL << 52	52
gresource	1ULL << 53	53
devicemanager	1ULL << 54	54
samgr	1ULL << 55	55
power	1ULL << 56	56
dsched	1ULL << 57	57
deviceprofile	1ULL << 58	58
dinput	1ULL << 59	59
bluetooth	1ULL << 60	60
accessibility	1ULL << 61	61
app	1ULL << 62	62

HiTraceOutputLevel

Enum Name (C/C++)	Enum Name (ArkTS)	Value	Trace Level
HITRACE_LEVEL_DEBUG	DEBUG	0	D
HITRACE_LEVEL_INFO	INFO	1	I
HITRACE_LEVEL_CRITICAL	CRITICAL	2	C
HITRACE_LEVEL_COMMERCIAL	COMMERCIAL	3	M

User-Mode Trace Format Before API version 19

Synchronous trace

• Start format: [Type identifier]|[Process ID]|H:[ID of the distributed call chain tracing task]#[Content]

• End format: [Type identifier]|[Process ID]

Asynchronous trace

• Start format: [Type identifier]|[Process ID]|H:[ID of the distributed call chain tracing task]#[Content] [Asynchronous task ID]

• End format: [Type identifier]|[Process ID]|H:[ID of the distributed call chain tracing task]#[Content] [Asynchronous task ID]

Integer value trace

• Trace format: [Type identifier]|[Process ID]|H:[ID of the distributed call chain tracing task]#[Content] [Integer value]

NOTE

The start and end formats of an asynchronous trace are the same. In versions earlier than API version 19, the asynchronous task ID and integer value fields are separated from the content field by spaces.

Sample Trace Logs in Different Scenarios Before API Version 19

Trace Type	Format When HiTraceChain is Enabled	Format When HiTraceChain is Disabled
Start a synchronous trace logging	B|1234|H:[a92ab94c18e1341,0,0]#tracename	B|1234|H:tracename
Stop a synchronous trace logging	E|1234|	E|1234|
Start an asynchronous trace logging	S|1234|H:[a92ab94c18e1341,0,0]#tracename 428	S|1234|H:tracename 428
Stop an asynchronous trace logging	F|1234|H:[a92ab94c18e1341,0,0]#tracename 428	F|1234|H:tracename 428
Trace of an integer value	C|1234|H:[a92ab94c18e1341,0,0]#tracename 5678	C|1234|H:tracename 5678

In the preceding samples, the process ID is 1234 and the content is tracename. When HiTraceChain is enabled, the ID of the distributed call chain tracing task is [a92ab94c18e1341,0,0]. The asynchronous task ID is 428, and the integer value to trace is 5678.