1# 订阅主线程超时事件（ArkTS） 2 3## 接口说明 4 5API接口的具体使用说明（参数使用限制、具体取值范围等）请参考[应用事件打点API文档](../reference/apis-performance-analysis-kit/js-apis-hiviewdfx-hiappevent.md)。 6 7| 接口名 | 描述 | 8| --------------------------------------------------- | -------------------------------------------- | 9| addWatcher(watcher: Watcher): AppEventPackageHolder | 添加应用事件观察者，以添加对应用事件的订阅。 | 10| removeWatcher(watcher: Watcher): void | 移除应用事件观察者，以移除对应用事件的订阅。 | 11 12## 开发步骤 13 14以实现对发生主线程超时场景生成的主线程超时事件订阅为例，说明开发步骤。 15 161. 新建一个ArkTS应用工程，编辑工程中的“entry > src > main > ets > entryability > EntryAbility.ets”文件，导入依赖模块： 17 18 ```ts 19 import { hiAppEvent, hilog } from '@kit.PerformanceAnalysisKit'; 20 ``` 21 222. 编辑工程中的“entry > src > main > ets > entryability > EntryAbility.ets”文件，在onCreate函数中添加系统事件的订阅，示例代码如下： 23 24 ```ts 25 hiAppEvent.addWatcher({ 26 // 开发者可以自定义观察者名称，系统会使用名称来标识不同的观察者 27 name: "watcher", 28 // 开发者可以订阅感兴趣的系统事件，此处是订阅了主线程超时事件 29 appEventFilters: [ 30 { 31 domain: hiAppEvent.domain.OS, 32 names: [hiAppEvent.event.MAIN_THREAD_JANK] 33 } 34 ], 35 // 开发者可以自行实现订阅实时回调函数，以便对订阅获取到的事件数据进行自定义处理 36 onReceive: (domain: string, appEventGroups: Array<hiAppEvent.AppEventGroup>) => { 37 hilog.info(0x0000, 'testTag', `HiAppEvent onReceive: domain=${domain}`); 38 for (const eventGroup of appEventGroups) { 39 // 开发者可以根据事件集合中的事件名称区分不同的系统事件 40 hilog.info(0x0000, 'testTag', `HiAppEvent eventName=${eventGroup.name}`); 41 for (const eventInfo of eventGroup.appEventInfos) { 42 // 开发者可以对事件集合中的事件数据进行自定义处理，此处是将事件数据打印在日志中 43 hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.domain=${eventInfo.domain}`); 44 hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.name=${eventInfo.name}`); 45 hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.eventType=${eventInfo.eventType}`); 46 // 开发者可以获取到主线程超时事件发生的时间戳 47 hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.time=${eventInfo.params['time']}`); 48 // 开发者可以获取到主线程超时应用的版本信息 49 hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.bundle_version=${eventInfo.params['bundle_version']}`); 50 // 开发者可以获取到主线程超时应用的包名 51 hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.bundle_name=${eventInfo.params['bundle_name']}`); 52 // 开发者可以获取到主线程超时应用的pid、uid 53 hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.pid=${eventInfo.params['pid']}`); 54 hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.uid=${eventInfo.params['uid']}`); 55 // 开发者可以获取主线程处理开始和结束时间 56 hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.begin_time=${eventInfo.params['begin_time']}`); 57 hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.end_time=${eventInfo.params['end_time']}`); 58 // 开发者可以获取到主线程超时事件发生时的故障日志文件 59 hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.external_log=${JSON.stringify(eventInfo.params['external_log'])}`); 60 hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.log_over_limit=${eventInfo.params['log_over_limit']}`); 61 } 62 } 63 } 64 }); 65 ``` 66 67 683. 编辑工程中的“entry > src > main > ets > pages> Index.ets”文件，添加一个Button控件onClick中实现主线程超时代码，示例代码如下： 69 ```ts 70 Button("timeOut350") 71 .fontSize(50) 72 .fontWeight(FontWeight.Bold) 73 .onClick(() => { 74 let t = Date.now(); 75 while (Date.now() - t <= 350) {} 76 }) 77 ``` 78 794. **开发者使用nolog版本，开发者模式处于关闭状态**，可以使能主线程超时检测抓取trace的功能。 80 815. 点击DevEco Studio界面中的运行按钮，运行应用工程，连续点击两次timeOut350按钮，会触发主线程超时事件。 82 836. 主线程超时事件上报后，系统会回调应用的onReceive函数，可以在Log窗口看到对系统事件数据的处理日志： 84 85 主线程超时事件采样栈示例： 86 87 ```text 88 HiAppEvent eventInfo.domain=OS 89 HiAppEvent eventInfo.name=MAIN_THREAD_JANK 90 HiAppEvent eventInfo.eventType=1 91 HiAppEvent eventInfo.params.time=1717593620518 92 HiAppEvent eventInfo.params.bundle_version=1.0.0 93 HiAppEvent eventInfo.params.bundle_name=com.example.main_thread_jank 94 HiAppEvent eventInfo.params.pid=40986 95 HiAppEvent eventInfo.params.uid=20020150 96 HiAppEvent eventInfo.params.begin_time=1717593620016 97 HiAppEvent eventInfo.params.end_time=1717593620518 98 HiAppEvent eventInfo.params.external_log=["/data/storage/el2/log/watchdog/MAIN_THREAD_JANK_20240613211739_40986.txt"] 99 HiAppEvent eventInfo.params.log_over_limit=false 100 ``` 101 102 主线程超时事件采样trace，与采样栈的结果大致相同，不同的地方： 103 104 栈： 105 external_log=["/data/storage/el2/log/watchdog/MAIN_THREAD_JANK_yyyyMMDDHHmmss_xxxx.txt"]。xxxx：代表进程pid 106 107 trace： 108 external_log=[""/data/storage/el2/log/watchdog/MAIN_THREAD_JANK_unix时间戳_xxxx.trace"]。xxxx：代表进程pid 109 110## 主线程超时事件时间规格 1111. 启动时间 112 113 主线程超时采样栈（150ms < 主线程处理时长 < 450ms）。**同一个应用的PID一个生命周期仅会触发一次主线程超时事件采样栈。** 114 115 主线程超时采样Trace（主线程处理时长 > 450ms）。**同一个应用的UID一天仅会触发一次主线程超时事件采样trace。** 116 1172. 抓栈时间 118 119 主线程处理事件超时后，开始执行周期性任务检测，每隔155ms检测主线程是否再次发生超时事件(1 <= 检测次数 <= 2)，共三种情况： 120 121 (1) 第一次检测发现超时事件，开始执行堆栈采样，每隔155ms采样一次，共采样10次堆栈，第11次收集堆栈并上报事件，结束检测。 122 123  124 125 (2) 第一次检测未发生超时事件，第二次检测发现超时事件，开始执行堆栈采样，每隔155ms采样一次，共采样10次堆栈，第11次收集堆栈并上报事件，结束检测。 126 127  128 129 (3) 两次检测均未发现超时事件，结束检测。 130 131  132 1333. 抓trace时间 134 135 主线程超时抓Trace调用录制函数后，每隔150ms检测主线程是否再次发生超时事件(检测次数 = 20)，其中，只要在20个间隔检测时，有一次主线程事件超时150ms，3s检测结束后落盘trace。 136 137 (1) 20次检测均未发生主线程超时150ms事件 138 139  140 141 (2) 20次检测至少有一次发生主线程超时150ms事件 142 143  144 145## 主线程超时事件规格 146 1471. 日志老化规格 148 149 一般情况，栈文件的大小为7-10KB，trace文件大小为3-6M。应用沙箱内的watchdog目录最大保存10M内容，超出后，需要用户手动清理文件。目录地址：/data/app/el2/100/log/应用bundle name/watchdog。 150 1512. 事件里如何获取日志：从external_logs中获取日志路径 152 1533. 抓栈功能目前只支持ARM64架构，抓栈结果为解析后的混合栈信息，包含native帧和JS帧 154 155 抓栈结果部分示例如下： 156 ```text 157 9 #00 pc 0000757c /system/bin/appspawn(55679d09bcdea35bb1e0d4e1d9a3e58f) 158 9 #01 pc 000731c0 /system/lib/ld-musl-aarch64.so.1(add9e521e4eaf5cb009d4260f3b69ccd) 159 9 #02 pc 000090a9 /system/bin/appspawn(main+396)(55679d09bcdea35bb1e0d4e1d9a3e58f) 160 9 #03 pc 0000ab5d /system/bin/appspawn(AppSpawnRun+100)(55679d09bcdea35bb1e0d4e1d9a3e58f) 161 9 #04 pc 0000e7f1 /system/lib/chipset-pub-sdk/libbegetutil.z.so(RunLoop_+200)(52ace27d827ad482439bf32cc75bb17b) 162 ...... 163 9 #21 pc 00107aec /system/lib/ld-musl-aarch64.so.1(__pthread_cond_timedwait+628)(add9e521e4eaf5cb009d4260f3b69ccd) 164 1 #00 pc 00032e67 /system/lib/platformsdk/libmmi-util.z.so(OHOS::MMI::UDSSocket::OnReadPackets(OHOS::MMI::CircleStreamBuffer&, std::__h::function<void (OHOS::MMI::NetPacket&)>)+158)(99e56bc765f9208f7b7ba8b268886a59) 165 1 #01 pc 0000312e5 /system/lib/platformsdk/libmmi-client.z.so(OHOS::MMI::ClientMsgHandler::OnMsgHandler(OHOS::MMI::UDSClient const&, OHOS::MMI::NetPacket&)+340)(66ac85e964777ae89f0c26c339093cd1) 166 1 #02 pc 0003016b /system/lib/platformsdk/libmmi-client.z.so(OHOS::MMI::ClientMsgHandler::OnPointerEvent(OHOS::MMI::UDSClient const&, OHOS::MMI::NetPacket&)+1222)(66ac85e964777ae89f0c26c339093cd1) 167 1 #03 pc 0003b96b /system/lib/platformsdk/libmmi-client.z.so(OHOS::MMI::InputManagerImpl::OnPointerEvent(std::__h::shared_ptr<OHOS::MMI::PointerEvent>)+1370)(66ac85e964777ae89f0c26c339093cd1) 168 1 #04 pc 00095903 /system/lib/platformsdk/libwm.z.so(OHOS::Rosen::InputEventListener::OnInputEvent(std::__h::shared_ptr<OHOS::MMI::PointerEvent>) const+478)(9c40c5f416d6f830435126998fbcad42) 169 ...... 170 1 #21 pc 003f5c55 /system/lib/platformsdk/libark_jsruntime.so(4e6a2651ec80a7f639233f414d6486fe) 171 1 #22 at anonymous (/entry/build/default/cache/default/default@CompileArkTS/esmodule/debug/entry/src/main/ets/pages/Index.js:67:17) 172 1 #23 at wait2 (/entry/build/default/cache/default/default@CompileArkTS/esmodule/debug/entry/src/main/ets/pages/Index.js:16:12) 173 ...... 174 ``` 175 176 每次抓栈拷贝16KB主线程调用栈信息进行回栈解析，所以每一次抓栈结果最多可以展示进程16KB调用信息，共进行10次，重复栈帧会聚合在一起，不同调用层次通过行缩进进行区分，最终以树型方式进行展示。当抓栈失败（如主线程阻塞在内核或信号被屏蔽等情况）时，将会输出"/proc/self/wchan"文件内容。 177 178 展示结果中每一行表示一个栈信息，每一行栈帧信息所表示的意义可以按如下方式解读： 179 180 native帧格式如下： 181 182 ```text 183 9 #02 pc 000090a9 /system/bin/appspawn(main+396)(55679d09bcdea35bb1e0d4e1d9a3e58f) 184 ^ ^ ^ ^ ^ ^ 185 1 2 3 4 5 6 186 187 1 表示采样到此帧的次数 188 2 表示帧的调用层级，行缩进大小与该层级对应，所有同一层级帧采样到的次数和不大于10次，#00采样次数和为10(设置采样的次数) 189 3 为native帧PC值 190 4 表示调用的文件路径 191 5 调用的函数名及代码行偏移(unstripped版本，stripped版本可能没有) 192 6 so文件md5值 193 ``` 194 195 JS帧格式如下： 196 197 ```text 198 1 #23 at wait2 (/entry/build/default/cache/default/XXX/entry/src/main/ets/pages/Index.js:16:12) 199 ^ ^ ^ ^ 200 1 2 3 4 201 202 1 表示采样到此帧的次数，同样最大为采样次数 203 2 表示帧的调用层级，与native帧意义相同 204 3 表示调用函数名wait2 205 4 表示调用函数所在的路径，文件及行列号 206 ``` 207 2084. trace规格简介 209 210 trace大小为1-5M，对于trace文件的解析可以使用[smpartperf在线工具](https://www.smartperf.host)进行解读. 211 212 导入trace文件后页面解读：从上往下主要展示时间轴、cpu使用率、cpu使用情况、进程间通讯数据的方法调用情况、进程、线程和方法调用情况，由此可以在事件维度上对这些数据进行直观展示。 213 214 更多对trace文件使用的介绍可以参考：[web端加载trace说明](https://gitee.com/openharmony/developtools_smartperf_host/blob/master/ide/src/doc/md/quickstart_systemtrace.md) 215
