1# Development of Performance Tracing 2 3## Introduction 4 5hiTraceMeter provides APIs for system performance tracing. You can call the APIs provided by the hiTraceMeter module in your own service logic to effectively track service processes and check the system performance. 6 7## Basic Concepts 8 9- **hiTraceMeter Tag** 10 11 Tag used for tracing data categorization. It is also known as **hiTraceMeter Category**. Generally, one subsystem maps to a tag. The tag is passed as the **Tag** parameter in performance tracing APIs. When you use the hiTraceMeter CLI tool to collect tracing data, only the tracing data specified by the **Tag** parameter is collected. 12 13## Working Principles 14 15- The application calls hiTraceMeter APIs to perform performance tracing. The APIs output the tracing data to the kernel's ftrace data buffer through the kernel's sysfs file interface. 16- The hiTraceMeter CLI tool reads the tracing data in the ftrace data buffer and saves the trace data as a text file on the device. 17 18## Constraints 19 20- Due to the asynchronous I/O feature of JS, the hiTraceMeter module provides only asynchronous APIs. 21 22## Available APIs 23 24The performance tracing APIs are provided by the **hiTraceMeter** module. For details, see [API Reference]( ../reference/apis/js-apis-hitracemeter.md). 25 26**APIs for performance tracing** 27 28| API | Return Value | Description | 29| ---------------------------------------------------------------------------- | --------- | ------------ | 30| hiTraceMeter.startTrace(name: string, taskId: number) | void | Marks the start of a trace task. If multiple trace tasks with the same name need to be performed at the same time or a trace task needs to be performed multiple times concurrently, different task IDs must be specified in **startTrace**. If the trace tasks with the same name are not performed at the same time, the same task ID can be used.| 31| hiTraceMeter.finishTrace(name: string, taskId: number) | void | Marks the end of a trace task. The values of **name** and **taskId** must be the same as those of **hiTraceMeter.startTrace**.| 32| hiTraceMeter.traceByValue(name: string, value: number) | void | Marks the value changes of a numeric variable in a trace task.| 33 34## How to Develop 35 36In this example, distributed call chain tracing begins when the application startup execution page is loaded and stops when the service usage is completed. 37 381. Create a project, and call hiTraceMeter APIs in the service logic to implement performance tracing. 39 40 - **ArkTS application project** 41 42 Create an ArkTS application project. In the displayed **Project** window, choose **entry** > **src** > **main** > **ets** > **pages** > **index**, and double-click **index.js**. Add the code to implement performance tracing upon page loading. For example, if the name of the trace task is **HITRACE\_TAG\_APP**, the sample code is as follows: 43 44 ```ts 45 import hitrace from '@ohos.hiTraceMeter'; 46 47 @Entry 48 @Component 49 struct Index { 50 @State message: string = 'Hello World'; 51 52 build() { 53 Row() { 54 Column() { 55 Text(this.message) 56 .fontSize(50) 57 .fontWeight(FontWeight.Bold) 58 .onClick(() => { 59 this.message = 'Hello ArkUI'; 60 61 // Start trace tasks with the same name concurrently. 62 hitrace.startTrace("HITRACE_TAG_APP", 1001); 63 // Keep the service process running. 64 console.log(`HITRACE_TAG_APP running`); 65 66 // Start the second trace task with the same name while the first task is still running. The tasks are running concurrently and therefore their taskId must be different. 67 hitrace.startTrace("HITRACE_TAG_APP", 1002); 68 // Keep the service process running. 69 console.log(`HITRACE_TAG_APP running`); 70 71 hitrace.finishTrace("HITRACE_TAG_APP", 1001); 72 hitrace.finishTrace("HITRACE_TAG_APP", 1002); 73 74 // If trace tasks with the same name are not run concurrently, the same taskId can be used. 75 hitrace.startTrace("HITRACE_TAG_APP", 1003); 76 // Keep the service process running. 77 console.log(`HITRACE_TAG_APP running`); 78 // End the first trace task. 79 hitrace.finishTrace("HITRACE_TAG_APP", 1003); 80 81 // Start the second trace task with the same name in serial mode. It uses a taskId different from the first trace task. 82 hitrace.startTrace("HITRACE_TAG_APP", 1004); 83 // Keep the service process running. 84 console.log(`HITRACE_TAG_APP running`); 85 let traceCount = 3; 86 hitrace.traceByValue("myTestCount", traceCount); 87 hitrace.finishTrace("HITRACE_TAG_APP", 1004); 88 89 // Start the third trace task with the same name in serial mode. It uses a taskId same as the second trace task. 90 hitrace.startTrace("HITRACE_TAG_APP", 1004); 91 // Keep the service process running. 92 console.log(`HITRACE_TAG_APP running`); 93 // End the third trace task. 94 hitrace.finishTrace("HITRACE_TAG_APP", 1004); 95 96 }) 97 } 98 .width('100%') 99 } 100 .height('100%') 101 } 102 } 103 ``` 104 105 - **JS application project** 106 107 Create a JS application project. In the displayed **Project** window, choose **entry** > **src** > **main** > **js** > **default** > **pages** > **index**, and double-click **index.js**. Add the code to implement performance tracing upon page loading. The sample code is as follows: 108 109 ```js 110 import hiTraceMeter from '@ohos.hiTraceMeter' 111 112 export default { 113 data: { 114 title: "" 115 }, 116 onInit() { 117 this.title = this.$t('strings.world'); 118 119 // Start trace tasks with the same name concurrently. 120 hiTraceMeter.startTrace("business", 1); 121 // Keep the service process running. 122 console.log(`business running`); 123 hiTraceMeter.startTrace("business", 2); // Start the second trace task with the same name while the first task is still running. The tasks are running concurrently and therefore their taskId must be different. 124 // Keep the service process running. 125 console.log(`business running`); 126 hiTraceMeter.finishTrace("business", 1); 127 // Keep the service process running. 128 console.log(`business running`); 129 hiTraceMeter.finishTrace("business", 2); 130 131 // Start trace tasks with the same name in serial mode. 132 hiTraceMeter.startTrace("business", 1); 133 // Keep the service process running. 134 console.log(`business running`); 135 hiTraceMeter.finishTrace("business", 1); // End the first trace task. 136 // Keep the service process running. 137 console.log(`business running`); 138 hiTraceMeter.startTrace("business", 1); // Start the second trace task with the same name in serial mode. 139 // Keep the service process running. 140 console.log(`business running`); 141 142 let traceCount = 3; 143 hiTraceMeter.traceByValue("myTestCount", traceCount); 144 traceCount = 4; 145 hiTraceMeter.traceByValue("myTestCount", traceCount); 146 hiTraceMeter.finishTrace("business", 1); 147 } 148 } 149 ``` 150 1512. Click the run button on the application page. Then, run the following commands in sequence in shell: 152 153 ```shell 154 hdc shell 155 hitrace --trace_begin app 156 ``` 157 158 After the trace command is executed, call the hiTraceMeter APIs in your own service logic on the device. Then, run the following commands in sequence: 159 160 ```shell 161 hitrace --trace_dump | grep tracing_mark_write 162 hitrace --trace_finish 163 ``` 164 165 The following is an example of the captured trace data: 166 167 ``` 168 <...>-3310 (-------) [005] .... 351382.921936: tracing_mark_write: S|3310|H:HITRACE_TAG_APP 1001 169 <...>-3310 (-------) [005] .... 351382.922138: tracing_mark_write: S|3310|H:HITRACE_TAG_APP 1002 170 <...>-3310 (-------) [005] .... 351382.922165: tracing_mark_write: F|3310|H:HITRACE_TAG_APP 1001 171 <...>-3310 (-------) [005] .... 351382.922175: tracing_mark_write: F|3310|H:HITRACE_TAG_APP 1002 172 <...>-3310 (-------) [005] .... 351382.922182: tracing_mark_write: S|3310|H:HITRACE_TAG_APP 1003 173 <...>-3310 (-------) [005] .... 351382.922203: tracing_mark_write: F|3310|H:HITRACE_TAG_APP 1003 174 <...>-3310 (-------) [005] .... 351382.922210: tracing_mark_write: S|3310|H:HITRACE_TAG_APP 1004 175 <...>-3310 (-------) [005] .... 351382.922233: tracing_mark_write: C|3310|H:myTestCount 3 176 <...>-3310 (-------) [005] .... 351382.922240: tracing_mark_write: F|3310|H:HITRACE_TAG_APP 1004 177 <...>-3310 (-------) [005] .... 351382.922247: tracing_mark_write: S|3310|H:HITRACE_TAG_APP 1004 178 <...>-3310 (-------) [005] .... 351382.922266: tracing_mark_write: F|3310|H:HITRACE_TAG_APP 1004 179 ``` 180