1# 订阅资源泄漏事件（ArkTS） 2 3<!--Kit: Performance Analysis Kit--> 4<!--Subsystem: HiviewDFX--> 5<!--Owner: @xuxinao--> 6<!--Designer: @peterhuangyu--> 7<!--Tester: @gcw_KuLfPSbe--> 8<!--Adviser: @foryourself--> 9 10## 接口说明 11 12本文介绍如何使用HiAppEvent提供的ArkTS接口订阅资源泄漏事件。接口的具体使用说明（参数使用限制、具体取值范围等）请参考[@ohos.hiviewdfx.hiAppEvent (应用事件打点)ArkTS API文档](../reference/apis-performance-analysis-kit/js-apis-hiviewdfx-hiappevent.md)。 13 14 15### 自定义参数设置接口描述 16 17| 接口名 | 描述 | 18| -------- | -------- | 19| setEventParam(params: Record<string, ParamType>, domain: string, name?: string): Promise<void> | 此方法用于设置事件的自定义参数，在资源泄漏检测事件中，仅支持设置JS内存泄漏事件的参数。<br />**说明**：从API version 20开始，支持该接口。 | 20 21### 自定义配置设置接口描述 22 23| 接口名 | 描述 | 24| -------- | -------- | 25| setEventConfig(name: string, config: Record<string, ParamType>): Promise<void> | 此方法用于设置事件的自定义配置。在资源泄漏检测事件中，仅支持设置js内存泄漏事件的配置。<br />**说明**：从API version 20开始，支持该接口。 | 26 27### 接口描述 28 29| 接口名 | 描述 | 30| -------- | -------- | 31| addWatcher(watcher: Watcher): AppEventPackageHolder | 添加应用事件观察者以订阅应用事件。 | 32| removeWatcher(watcher: Watcher): void | 移除应用事件观察者，取消对应用事件的订阅。 33## 开发步骤 34 35以订阅发生内存泄漏场景生成的资源泄漏事件为例，说明开发步骤。 36 37### 步骤一：新建工程 38 391. 在DevEco Studio中新建工程，选择“Empty Ability”，编辑工程中的“entry > src > main > ets > entryability > EntryAbility.ets”文件，导入依赖模块： 40 41 ```ts 42 import { hiAppEvent, hilog, hidebug } from '@kit.PerformanceAnalysisKit'; 43 ``` 44 452. 编辑工程中的“entry > src > main > ets > entryability > EntryAbility.ets”文件，在onCreate函数中添加系统事件的订阅，示例代码如下： 46 47 ```ts 48 // 完成参数键值对赋值 49 let params: Record<string, hiAppEvent.ParamType> = { 50 "test_data": 100, 51 }; 52 // 设置资源泄漏事件的自定义参数 53 hiAppEvent.setEventParam(params, hiAppEvent.domain.OS, hiAppEvent.event.RESOURCE_OVERLIMIT).then(() => { 54 hilog.info(0x0000, 'testTag', `HiAppEvent success to set event param`); 55 }).catch((err: BusinessError) => { 56 hilog.error(0x0000, 'testTag', `HiAppEvent code: ${err.code}, message: ${err.message}`); 57 }); 58 // 完成自定义配置键值对赋值 59 let configParams: Record<string, hiAppEvent.ParamType> = { 60 "js_heap_logtype": "event", // 仅获取事件 61 } 62 // 设置资源泄漏事件的自定义配置 63 hiAppEvent.setEventConfig(hiAppEvent.event.RESOURCE_OVERLIMIT, configParams); 64 hiAppEvent.addWatcher({ 65 // 自定义观察者名称，系统会使用名称来标识不同的观察者 66 name: "watcher", 67 // 订阅感兴趣的系统事件，此处是订阅了资源泄漏事件 68 appEventFilters: [ 69 { 70 domain: hiAppEvent.domain.OS, 71 names: [hiAppEvent.event.RESOURCE_OVERLIMIT] 72 } 73 ], 74 // 自行实现订阅实时回调函数，以便对订阅获取到的事件数据进行自定义处理 75 onReceive: (domain: string, appEventGroups: Array<hiAppEvent.AppEventGroup>) => { 76 hilog.info(0x0000, 'testTag', `HiAppEvent onReceive: domain=${domain}`); 77 for (const eventGroup of appEventGroups) { 78 // 根据事件集合中的事件名称区分不同的系统事件 79 hilog.info(0x0000, 'testTag', `HiAppEvent eventName=${eventGroup.name}`); 80 for (const eventInfo of eventGroup.appEventInfos) { 81 // 获取到资源泄漏事件发生时内存信息 82 hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo=${JSON.stringify(eventInfo)}`); 83 } 84 } 85 } 86 }); 87 ``` 88 89### 步骤二：订阅资源泄漏事件 90 911. 编辑工程中的“entry > src > main > ets > pages > Index.ets”文件，添加按钮并在其onClick函数构造资源泄漏场景，以触发资源泄漏事件。 92 93 此处需要使用[hidebug.setAppResourceLimit](../reference/apis-performance-analysis-kit/js-apis-hidebug.md#hidebugsetappresourcelimit12)设置内存限制，造成内存泄漏，同步在“开发者选项”中打开“系统资源泄漏日志”（开关状态变更后需重启设备）。 94 95 <!--RP1--> 96 资源泄漏问题定位可参考[内存泄漏分析](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-insight-session-snapshot)。 97 <!--RP1End--> 98 99 接口示例代码如下： 100 101 ```ts 102 import { hidebug } from '@kit.PerformanceAnalysisKit'; 103 104 @Entry 105 @Component 106 struct Index { 107 @State leakedArray: string[][] = []; 108 109 build() { 110 Column() { 111 Row() { 112 Column() { 113 Button("pss leak") 114 .onClick(() => { 115 hidebug.setAppResourceLimit("pss_memory", 1024, true); 116 for (let i = 0; i < 20 * 1024; i++) { 117 this.leakedArray.push(new Array(1).fill("leak")); 118 } 119 }) 120 Button("js leak") 121 .onClick(() => { 122 for (let i = 0; i < 10000; i++) { 123 this.leakedArray.push(new Array(500000).fill(1)); 124 } 125 }) 126 } 127 } 128 .height('100%') 129 .width('100%') 130 } 131 } 132 } 133 ``` 134 1352. 点击DevEco Studio界面中的运行按钮，运行应用工程，点击“pss leak”按钮，等待15~30分钟，系统会上报pss内存泄漏事件。 136 同一个应用，24小时内至多上报一次资源泄漏事件，如果短时间内要二次上报，需要重启设备。 137 1383. pss内存泄漏事件上报后，系统会回调应用的onReceive函数，可以在Log窗口看到对系统事件数据的处理日志： 139 140 ```text 141 HiAppEvent onReceive: domain=OS 142 HiAppEvent eventName=RESOURCE_OVERLIMIT 143 HiAppEvent eventInfo={"domain":"OS","name":"RESOURCE_OVERLIMIT","eventType":1,"params":{"bundle_name":"com.example.myapplication","bundle_version":"1.0.0","memory":{"pss":2100257,"rss":1352644,"sys_avail_mem":250272,"sys_free_mem":60004,"sys_total_mem":1992340,"vss":2462936},"pid":20731,"resource_type":"pss_memory","time":1502348798106,"uid":20010044,"external_log": ["/data/storage/el2/log/resourcelimit/RESOURCE_OVERLIMIT_1725614572401_6808.log", "/data/storage/el2/log/resourcelimit/RESOURCE_OVERLIMIT_1725614572412_6808.log"], "log_over_limit": false}} 144 ``` 145 146 如上，eventInfo中包含资源泄漏事件的[params字段](hiappevent-watcher-resourceleak-events.md#params字段说明)，可以根据eventInfo中的resource_type字段来判断当前的泄漏类型。 147 1484. 提前在“开发者选项”中开启“系统资源泄漏日志”开关（开启或关闭开关均需重启设备）。点击 DevEco Studio 窗口中的运行按钮，运行应用工程。点击“js leak”按钮，等待 3 到 5 秒，应用会闪退。重新打开应用后，系统将上报js内存泄漏事件。 149 同一个应用，24小时内至多上报一次js内存泄漏，如果短时间内要二次上报，需要重启设备。 150 1515. js内存泄漏事件上报后，系统会回调应用的onReceive函数，在该函数中可在Log窗口查看系统事件数据的处理日志。 152 153 ```text 154 HiAppEvent onReceive: domain=OS 155 HiAppEvent eventName=RESOURCE_OVERLIMIT 156 HiAppEvent eventInfo={"domain":"OS","name":"RESOURCE_OVERLIMIT","eventType":1,"params":{"bundle_name":"com.example.myapplication","bundle_version":"1.0.0","external_log":[],"log_over_limit":true,"memory":{"limit_size":0,"live_object_size":0},"pid":14941,"resource_type":"js_heap","test_data":100,"time":1752564700511,"uid":20020181}} 157 ``` 158 159 如上，eventInfo中的“test_data”字段即步骤一中设置的键值对的内容。 160 161### 步骤三：nolog版本订阅js_heap快照 162 163请应用在收到该订阅事件后，首先从事件的external_log字段中获取堆快照文件存储路径，并将其尽快搬移或上传云，然后再删除原堆快照文件，以避免因应用沙箱路径目录剩余存储空间不足（最大2GB）导致下次堆快照文件无法生成。 164 165订阅后生成的.log日志文件需要将后缀名修改为.rawheap文件，再通过[translator工具](../tools/rawheap-translator.md)转换为.heapsnapshot文件，通过DevEco Studio或浏览器打开展示，详情见[Snapshot离线导入](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-snapshot-basic-operations#section6760173514388)。 166 167API version 14后，开发者可以将日志文件后缀名修改为.rawheap后，将其导入DevEco Studio并展示，详情见[Raw Heap离线导入](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-snapshot-basic-operations#section1888195110017)。 168 169提供两种方法，任选其一即可。 170 171 方法1. 应用需要在AppScope/app.json5文件中配置如下环境变量： 172 173 ```text 174 "appEnvironments": [ 175 { 176 "name": "DFX_RESOURCE_OVERLIMIT_OPTIONS", 177 "value": "oomdump:enable" 178 } 179 ] 180 ``` 181 182 **nolog版本虚拟机堆快照生成规格限制** 183 184 堆快照文件大小约为0.4至1.2GB（zip压缩后约为50至100MB）。由于体积较大，系统会对堆快照的生成次数进行管控，具体规格如下： 185 186 - 整机：每周生成js堆快照的次数为5次，若整机配额用完，则所有应用都无法继续生成堆快照； 187 - 应用：每周仅有1次生成js堆快照的机会，自应用触发oomdump功能后的7天内，无法再次触发； 188 - 如果整机剩余存储空间不足30GB，则不会触发oomdump功能。 189 190 开发者在调试期间，可通过将系统时间调整至7天后并重启设备的方式重置应用触发oomdump的次数，以便快速完成功能适配与验证。 191 192 > **注意：** 193 > 194 > json5配置文件中的value字段内容格式支持键值对集合“key1:value1;key2:value2;...”。目前系统仅支持配置如上键值对的应用，在nolog版本使能oomdump功能。 195 196 方法2. 应用调用setEventConfig并传入以下参数： 197 198 ```ts 199 let configParams: Record<string, hiAppEvent.ParamType> = { 200 "js_heap_logtype": "event_rawheap", 201 }; 202 203 hiAppEvent.setEventConfig(hiAppEvent.event.RESOURCE_OVERLIMIT, configParams); 204 ``` 205 206 方法2生成堆快照的数量**不**受到**nolog版本虚拟机堆快照生成规格限制**的约束。 207