1# Using hiTraceMeter (ArkTS/JS)
2
3## Overview
4
5**hiTraceMeter** provides APIs for system performance tracing. You can call the APIs provided by **hiTraceMeter** in key codes to track service processes and check the system performance.
6
7## Basic Concepts
8
9**hiTraceMeter Tag**: tag specifying the category of the data to trace. It is also known as **HiTraceMeter Category**. Generally, one subsystem maps to a tag. The tag is passed in by the **Tag** parameter in performance tracing APIs. When you use the hiTraceMeter CLI tool to collect tracing data, only the data specified by the **Tag** parameter is collected.
10
11## Working Principles
12
131. The application calls hiTraceMeter APIs to trace and output the tracing data to the kernel's ftrace buffer through the kernel's sysfs file interface.
14
152. The hiTraceMeter CLI tool reads the tracing data in the ftrace buffer and saves the trace data as a text file on the device.
16
17## Available APIs
18
19The performance tracing APIs are provided by the **hiTraceMeter** module. For details, see [Hitrace](../reference/apis-performance-analysis-kit/js-apis-hitracemeter.md).
20
21| API | Description |
22| -------- | -------- |
23| hiTraceMeter.startTrace(name: string, taskId: number) | Starts an asynchronous time slice trace task. If multiple tracing tasks with the same name need to be performed at the same time, different task IDs must be specified through **taskId**. If the tracing tasks with the same name are not performed at the same time, the same task ID can be used. |
24| hiTraceMeter.finishTrace(name: string, taskId: number) | Stops an asynchronous time slice trace task. The values of **name** and **taskId** must be the same as those of **hiTraceMeter.startTrace**. |
25| hiTraceMeter.traceByValue(name: string, value: number) | Traces the value changes of a numeric variable, which is an integer. |
26
27HiTraceMeter logging APIs are classified into three types by functionality/behavior: API for synchronous time slice tracing, API for asynchronous time slice tracing, and API for integer tracing. APIs for synchronous and asynchronous time slice tracing are synchronous and are used in the same thread. Cross-thread logging and analysis are not supported.
28
29- The API for synchronous time slice tracing is used for sequential logging, which is not supported in ArkTS/JS.
30- The API for asynchronous time slice tracing is used to start logging before an operation is called and end longing after the operation is complete. Since the start and end of asynchronous tracing do not occur in sequence, a unique task ID is used to identify the start and end of asynchronous tracing. The task ID is passed as a parameter of the API for asynchronous tracing.
31- The integer tracing API is used to trace numeric variables.
32
33## How to Develop
34
35In this example, distributed call chain tracing begins when the application startup execution page is loaded and stops when the service usage is completed.
36
371. In DevEco Studio, create an ArkTS application project. In the **Project** window, choose **entry** > **src** > **main** > **ets** > **pages** > **index**, and double-click **index.ets**. Add the code to the file to implement performance tracing upon page loading. The sample code of tracing task **myTraceTest** is as follows:
38
39   ```ts
40   import hiTraceMeter from '@ohos.hiTraceMeter';
41
42   @Entry
43   @Component
44   struct Index {
45     @State message: string = 'Hello World';
46
47     build() {
48       Row() {
49         Column() {
50           Text(this.message)
51             .fontSize(50)
52             .fontWeight(FontWeight.Bold)
53             .onClick(() => {
54               this.message = 'Hello Hitrace';
55
56               let traceCount = 0;
57               // Start the first tracing task.
58               hiTraceMeter.startTrace("myTraceTest", 1001);
59               // Start counting the task.
60               traceCount++;
61               hiTraceMeter.traceByValue("myTestCount", traceCount);
62               // Keep the service process running.
63               console.log(`myTraceTest running, taskid: 1001`);
64
65               // Start the second tracing task with the same name while the first task is still running. The tasks are running concurrently and therefore their taskId must be different.
66               hiTraceMeter.startTrace("myTraceTest", 1002);
67               // Start counting the task.
68               traceCount++;
69               hiTraceMeter.traceByValue("myTestCount", traceCount);
70               // Keep the service process running.
71               console.log(`myTraceTest running, taskid: 1002`);
72
73               // End the tracing task whose task ID is 1001.
74               hiTraceMeter.finishTrace("myTraceTest", 1001);
75               // End the tracing task whose task ID is 1002.
76               hiTraceMeter.finishTrace("myTraceTest", 1002);
77
78             })
79          }
80          .width('100%')
81        }
82        .height('100%')
83      }
84   }
85   ```
86
872. Click the **Run** button in DevEco Studio to run the project. Then, run the [hitrace](hitrace.md) command to obtain the tracing task logs.
88
89   Run the following command in DevEco Studio Terminal:
90
91   ```shell
92   PS D:\xxx\xxx> hdc shell
93   $ hitrace --trace_begin app
94   ```
95
96   After the **trace** command is executed, call the HiTraceMeter APIs in your service logic on the device. Then, run the following commands in sequence:
97
98   ```shell
99   $ hitrace --trace_dump | grep tracing_mark_write
100   $ hitrace --trace_finish
101   ```
102
103   The following is an example of the captured trace data:
104
105   ```text
106   <...>-3310    (-------) [005] .... 351382.921936: tracing_mark_write: S|3310|H:myTraceTest 1001
107   <...>-3310    (-------) [005] .... 351382.922233: tracing_mark_write: C|3310|H:myTestCount 1
108   <...>-3310    (-------) [005] .... 351382.922138: tracing_mark_write: S|3310|H:myTraceTest 1002
109   <...>-3310    (-------) [005] .... 351382.922233: tracing_mark_write: C|3310|H:myTestCount 2
110   <...>-3310    (-------) [005] .... 351382.922165: tracing_mark_write: F|3310|H:myTestCount 1001
111   <...>-3310    (-------) [005] .... 351382.922175: tracing_mark_write: F|3310|H:myTestCount 1002
112   ```
113