使用HiTraceMeter跟踪性能（ArkTS）

简介

HiTraceMeter提供系统性能打点接口。开发者在关键代码位置调用这些API，能够有效跟踪进程轨迹，查看系统和应用性能。

接口说明

性能打点跟踪接口由HiTraceMeter模块提供，详细API请参考@ohos.hiTraceMeter (性能打点)。

接口分类

HiTraceMeter打点接口分为三类：同步时间片跟踪、异步时间片跟踪和整数跟踪。HiTraceMeter接口实现均为同步，同步和异步针对的是被跟踪的业务。同步业务使用同步时间片跟踪接口，异步业务使用异步时间片跟踪接口。HiTraceMeter打点接口可与HiTraceChain一起使用，进行跨设备、跨进程或跨线程的打点关联与分析。

接口使用场景

• 同步时间片跟踪接口

  用于顺序执行的打点场景，需按序成对使用startSyncTrace()接口和finishSyncTrace()接口，否则会导致trace文件在smartperf等可视化工具上显示异常。

• 异步时间片跟踪接口

  在异步操作执行前调用startAsyncTrace()接口进行开始打点，在异步操作完成后调用finishAsyncTrace()接口进行结束打点。

  解析trace时，通过name和taskId参数识别不同的异步跟踪。这两个接口必须按序成对使用，并传入相同的name和taskId。

  不同的异步流程中应使用不同的name和taskId，但在异步跟踪流程不会同时发生的情况下，可以使用相同的name和taskId。

  调用错误会导致trace文件在smartperf等可视化工具上显示异常。

• 整数跟踪接口

  用于跟踪整数变量。整数值变动时调用traceByValue()接口，可在smartperf的泳道图中观察变动情况。由于从开始采集到首次打点存在时间差，这段时间的数值无法查看。

参数解析

开发步骤

以下为一个使用HiTraceMeter打点接口的ArkTS应用示例。

步骤一：创建项目

1. 在DevEco Studio中新建工程，选择“Empty Ability”，工程的目录结构如下：

   ├── entry
   │   ├── src
   │       ├── main
   │       │   ├── ets
   │       │   │   ├── entryability
   │       │   │   │   └── EntryAbility.ets
   │       │   │   └── pages
   │       │   │       └── Index.ets

2. 编辑工程中的“entry > src > main > ets > pages > Index.ets”：

   导入所需依赖：

   import { hiTraceMeter, hilog} from '@kit.PerformanceAnalysisKit';

   Index.ets

   定义测试方法：

   function testHiTraceMeterASync() {
     const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL;
     hiTraceMeter.startAsyncTrace(COMMERCIAL, 'myTestAsyncTrace', 1001, 'categoryTest', 'key=value');
     hiTraceMeter.startAsyncTrace(COMMERCIAL, 'myTestAsyncTrace', 1002, 'categoryTest', 'key=value');
   
     setTimeout(() => {
       // 结束taskId为1001的异步跟踪任务
       hiTraceMeter.finishAsyncTrace(COMMERCIAL, 'myTestAsyncTrace', 1001);
     }, 2000);
   
     setTimeout(() => {
       // 结束taskId为1002的异步跟踪任务
       hiTraceMeter.finishAsyncTrace(COMMERCIAL, 'myTestAsyncTrace', 1002);
     }, 1000);
   }
   
   function testHiTraceMeterSync() {
     const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL;
     // 开始同步跟踪任务
     hiTraceMeter.startSyncTrace(COMMERCIAL, 'myTestSyncTrace', 'key=value');
     // 业务流程
     hilog.info(0x0000, 'testTrace', 'myTraceTest running, synchronizing trace');
     // 结束同步跟踪任务
     hiTraceMeter.finishSyncTrace(COMMERCIAL);
   }
   
   function testHiTraceMeterValue() {
     const COMMERCIAL = hiTraceMeter.HiTraceOutputLevel.COMMERCIAL;
     let traceCount = 0;
     // trace计数初始值
     hiTraceMeter.traceByValue(COMMERCIAL, 'myTestCountTrace', traceCount);
     traceCount++;
     // trace打点变化后的值
     hiTraceMeter.traceByValue(COMMERCIAL, 'myTestCountTrace', traceCount);
   }
   
   function testHiTraceMeter() {
     // 在未开启应用trace捕获时，避免该部分性能损耗
     if (hiTraceMeter.isTraceEnabled()) {
       testHiTraceMeterASync();
       testHiTraceMeterSync();
       testHiTraceMeterValue();
     } else {
       hilog.info(0x0000, 'testTrace', 'myTraceTest running, trace is not enabled');
     }
   }

   Index.ets

   添加按钮以触发接口调用：

   Button("testHiTraceMeter").backgroundColor('#FFFF00FF')
     .onClick(testHiTraceMeter)

   Index.ets

步骤二：采集trace信息并查看

1. 在DevEco Studio Terminal窗口中执行以下命令，开启应用的trace捕获。

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

2. 单击DevEco Studio界面上的运行按钮，启动应用。点击应用界面的“testHiTraceMeter”按钮，执行包含HiTraceMeter打点的业务逻辑。然后执行如下命令抓取trace数据，并使用“myTest”关键字过滤trace数据（示例打点接口传递的name字段前缀均为“myTest”）。

   $ hitrace --trace_dump | grep myTest

   成功抓取的trace数据如下所示：

   <...>-30265   (-------) [003] ..... 223860.709694: tracing_mark_write: S|30265|H:myTestAsyncTrace|1001|M62|categoryTest|key=value
   <...>-30265   (-------) [003] ..... 223860.709735: tracing_mark_write: S|30265|H:myTestAsyncTrace|1002|M62|categoryTest|key=value
   <...>-30265   (-------) [003] ..... 223860.710081: tracing_mark_write: B|30265|H:myTestSyncTrace|M62|key=value
   <...>-30265   (-------) [003] ..... 223860.710305: tracing_mark_write: C|30265|H:myTestCountTrace|0|M62
   <...>-30265   (-------) [003] ..... 223860.710332: tracing_mark_write: C|30265|H:myTestCountTrace|1|M62
   <...>-30265   (-------) [003] ..... 223861.711284: tracing_mark_write: F|30265|H:myTestAsyncTrace|1002|M62
   <...>-30265   (-------) [003] ..... 223862.709901: tracing_mark_write: F|30265|H:myTestAsyncTrace|1001|M62

   每一行trace数据中，tracing_mark_write为打点事件类型，应用程序中调用HiTraceMeter接口打点使用的均为此事件。打点事件类型前面的数据分别为线程名-线程ID、进程ID、CPU和打点时间（从开机到当前的时间，单位为秒）；打点事件类型后面的数据可查看用户态trace格式。

步骤三：停止采集trace

1. 执行以下命令，停止应用的trace捕获。

   $ hitrace --trace_finish

2. 再次点击应用界面的“testHiTraceMeter”按钮，此时应用trace捕获已关闭，isTraceEnabled()接口返回false。在DevEco Studio Log窗口使用关键字“not enabled”进行过滤，会打印如下日志。

   myTraceTest running, trace is not enabled

   说明

   log版本在使用hitrace --trace_finish命令停止采集后会自动拉起快照模式，打开trace捕获，此时isTraceEnabled()接口返回true，不会打印上述日志。