• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 订阅崩溃事件（ArkTS）
2<!--Kit: Performance Analysis Kit-->
3<!--Subsystem: HiviewDFX-->
4<!--Owner: @chenshi51-->
5<!--Designer: @Maplestory-->
6<!--Tester: @yufeifei-->
7<!--Adviser: @foryourself-->
8
9## 简介
10
11本文介绍如何使用HiAppEvent提供的ArkTS接口订阅应用崩溃事件。接口的详细使用说明（参数限制、取值范围等）请参考[@ohos.hiviewdfx.hiAppEvent (应用事件打点)ArkTS API文档](../reference/apis-performance-analysis-kit/js-apis-hiviewdfx-hiappevent.md)。
12
13> **说明：**
14>
15> 使用ArkTS接口可以订阅JsError和NativeCrash两种崩溃事件。
16
17## 接口说明
18
19| 接口名 | 描述 |
20| -------- | -------- |
21| addWatcher(watcher: Watcher): AppEventPackageHolder | 添加应用事件观察者，以添加对应用事件的订阅。 |
22| removeWatcher(watcher: Watcher): void | 移除应用事件观察者，以移除对应用事件的订阅。 |
23
24## 开发步骤
25
26### 添加事件观察者
27
28**建议在应用启动后、执行业务逻辑前添加事件观察者，以确保能够订阅到崩溃事件。**
29
30以订阅用户点击按钮触发崩溃生成的崩溃事件为例，说明开发步骤。
31
321. DevEco Studio新建Native C++模板工程，编辑“entry > src > main > ets > entryability > EntryAbility.ets”文件，导入依赖模块。示例代码如下：
33
34   ```ts
35   import { BusinessError } from '@kit.BasicServicesKit';
36   import { hiAppEvent, hilog } from '@kit.PerformanceAnalysisKit';
37   import testNapi from 'libentry.so';
38   ```
39
402. 编辑工程中的“entry > src > main > ets  > entryability > EntryAbility.ets”文件，在onCreate函数中设置事件的[崩溃事件自定义参数](hiappevent-watcher-crash-events.md#崩溃事件自定义参数设置)和[崩溃日志规格自定义参数](hiappevent-watcher-crash-events.md#崩溃日志规格自定义参数设置)，示例代码如下：
41
42   ```ts
43    // 构建崩溃事件的自定义参数
44    let params: Record<string, hiAppEvent.ParamType> = {
45      "test_data": 100,
46    };
47    // 开发者可以设置崩溃事件的自定义参数
48    hiAppEvent.setEventParam(params, hiAppEvent.domain.OS, hiAppEvent.event.APP_CRASH).then(() => {
49      hilog.info(0x0000, 'testTag', `HiAppEvent success to set event param`);
50    }).catch((err: BusinessError) => {
51      hilog.error(0x0000, 'testTag', `HiAppEvent code: ${err.code}, message: ${err.message}`);
52    });
53
54    // 构建崩溃日志规格自定义参数
55    let configParams: Record<string, hiAppEvent.ParamType> = {
56      "extend_pc_lr_printing": true, // 使能扩展打印pc和lr寄存器附近的内存值
57      "log_file_cutoff_sz_bytes": 102400, // 截断崩溃日志到100KB
58      "simplify_vma_printing": true // 使能精简打印maps
59    };
60
61    // 开发者可以设置崩溃日志配置参数
62    hiAppEvent.setEventConfig(hiAppEvent.event.APP_CRASH, configParams).then(() => {
63      hilog.info(0x0000, 'testTag', `HiAppEvent success to set event config.`);
64    }).catch((err: BusinessError) => {
65      hilog.error(0x0000, 'testTag', `HiAppEvent code: ${err.code}, message: ${err.message}`);
66    });
67   ```
68
693. 编辑工程中的“entry > src > main > ets > entryability > EntryAbility.ets”文件，在 `onCreate` 函数中添加系统事件的订阅。示例代码如下：
70
71   ```ts
72    let watcher: hiAppEvent.Watcher = {
73      // 开发者可以自定义观察者名称，系统会使用名称来标识不同的观察者
74      name: "watcher",
75      // 开发者可以订阅感兴趣的系统事件，此处是订阅了崩溃事件
76      appEventFilters: [
77        {
78          domain: hiAppEvent.domain.OS,
79          names: [hiAppEvent.event.APP_CRASH]
80        }
81      ],
82      // 开发者可以自行实现订阅实时回调函数，以便对订阅获取到的事件数据进行自定义处理
83      onReceive: (domain: string, appEventGroups: Array<hiAppEvent.AppEventGroup>) => {
84        hilog.info(0x0000, 'testTag', `HiAppEvent onReceive: domain=${domain}`);
85        for (const eventGroup of appEventGroups) {
86          // 开发者可以根据事件集合中的事件名称区分不同的系统事件
87          hilog.info(0x0000, 'testTag', `HiAppEvent eventName=${eventGroup.name}`);
88          for (const eventInfo of eventGroup.appEventInfos) {
89            // 开发者可以对事件集合中的事件数据进行自定义处理，此处是将事件数据打印在日志中
90            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.domain=${eventInfo.domain}`);
91            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.name=${eventInfo.name}`);
92            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.eventType=${eventInfo.eventType}`);
93            // 开发者可以获取到崩溃事件发生的时间戳
94            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.time=${eventInfo.params['time']}`);
95            // 开发者可以获取到崩溃事件发生的崩溃类型
96            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.crash_type=${eventInfo.params['crash_type']}`);
97            // 开发者可以获取到崩溃应用的前后台状态
98            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.foreground=${eventInfo.params['foreground']}`);
99            // 开发者可以获取到崩溃应用的版本信息
100            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.bundle_version=${eventInfo.params['bundle_version']}`);
101            // 开发者可以获取到崩溃应用的包名
102            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.bundle_name=${eventInfo.params['bundle_name']}`);
103            // 开发者可以获取到崩溃应用的进程id
104            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.pid=${eventInfo.params['pid']}`);
105            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.uid=${eventInfo.params['uid']}`);
106            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.uuid=${eventInfo.params['uuid']}`);
107            // 开发者可以获取到崩溃事件发生的异常类型、异常原因和异常调用栈
108            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.exception=${JSON.stringify(eventInfo.params['exception'])}`);
109            // 开发者可以获取到崩溃事件发生时日志信息
110            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.hilog.size=${eventInfo.params['hilog'].length}`);
111            // 开发者可以获取到崩溃事件发生时的崩溃日志文件
112            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.external_log=${JSON.stringify(eventInfo.params['external_log'])}`);
113            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.log_over_limit=${eventInfo.params['log_over_limit']}`);
114            // 开发者可以获取到崩溃事件的自定义数据test_data
115            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.test_data=${eventInfo.params['test_data']}`);
116          }
117        }
118      }
119    };
120    hiAppEvent.addWatcher(watcher);
121   ```
122
1234. 构造崩溃场景
124
125    - 构造NativeCrash类型崩溃
126
127      编辑工程中的“entry > src > main > cpp > napi_init.cpp”文件，Add方法中增加如下代码：
128
129      ```cpp
130      int *p = nullptr;
131      int a = *p; // 空指针解引用，程序会在此处崩溃
132      ```
133
134       编辑工程中的“entry > src > main > ets > pages > Index.ets”文件，添加按钮并在其onClick函数中构造崩溃场景，以触发崩溃事件。示例代码如下：
135
136      ```ts
137      Button("NativeCrash").onClick(()=>{
138        // 在按钮点击函数中调用napi_init.cpp中Add方法触发NativeCrash类型崩溃事件
139        testNapi.add(2, 3);
140      })
141      ```
142
143    - 构造JsError类型崩溃
144
145      编辑工程中的“entry > src > main > ets > pages > Index.ets”文件，添加按钮并在其onClick函数中构造崩溃场景，以触发崩溃事件。示例代码如下：
146
147      ```ts
148      Button("JsError").onClick(()=>{
149        // 在按钮点击函数中构造一个JsError类型崩溃，触发应用崩溃事件
150        let result: object = JSON.parse("");
151      })
152      ```
153
1545. 点击DevEco Studio界面的运行按钮，启动应用工程。在应用界面中点击“NativeCrash”或“JsError”按钮，触发崩溃事件。系统根据崩溃类型生成相应的日志并进行回调。
155
156> **说明：**
157>
158> JsError通过进程内采集故障信息触发回调，速度快，而NativeCrash采取进程外采集故障信息，平均耗时约2秒，具体受业务线程数量和进程间通信影响。开发者可订阅崩溃事件，故障信息采集完成后异步上报，不阻塞当前业务。
159
160### 验证观察者是否订阅到崩溃事件
161
162在应用主动捕获崩溃异常和未主动捕获崩溃异常的场景下，崩溃事件的回调时机不同，需在不同时间验证是否订阅到崩溃事件。
163
164**应用未主动捕获崩溃异常场景**
165
166若应用未主动捕获崩溃异常，系统处理崩溃后应用将退出。**应用下次启动时**，HiAppEvent将崩溃事件上报给已注册的监听，完成回调。
167
168**应用主动捕获崩溃异常场景**
169
170若应用主动捕获崩溃异常，崩溃事件将在**应用退出前**回调，例如以下两种情况：
171
1721. 异常处理中未主动退出，应用崩溃后将不会退出。
173
174   采用[errorManger.on](../reference/apis-ability-kit/js-apis-app-ability-errorManager.md#errormanageronerror)方法捕获异常会导致JsError类型的崩溃事件在应用退出前回调。若应用主动注册[崩溃信号](cppcrash-guidelines.md#系统处理的崩溃信号)处理函数但未主动退出，会导致NativeCrash类型的崩溃事件在应用退出前回调。
175
1762. 异常处理耗时过长，导致应用退出延迟。
177
178在开发调试阶段，HiAppEvent上报事件完成回调后，可以在DevEco Studio的HiLog窗口查看JsError类型崩溃事件内容。NativeCrash类型崩溃事件内容略有不同，具体参见[崩溃事件字段说明](hiappevent-watcher-crash-events.md#事件字段说明)。JsError类型崩溃事件内容样例如下：
179
180```text
181HiAppEvent onReceive: domain=OS
182HiAppEvent eventName=APP_CRASH
183HiAppEvent eventInfo.domain=OS
184HiAppEvent eventInfo.name=APP_CRASH
185HiAppEvent eventInfo.eventType=1
186HiAppEvent eventInfo.params.time=1711440614001
187HiAppEvent eventInfo.params.crash_type=JsError
188HiAppEvent eventInfo.params.foreground=true
189HiAppEvent eventInfo.params.bundle_version=1.0.0
190HiAppEvent eventInfo.params.bundle_name=com.example.myapplication
191HiAppEvent eventInfo.params.pid=2043
192HiAppEvent eventInfo.params.uid=20010043
193HiAppEvent eventInfo.params.uuid=b1e953ba0022c112e4502e28e8b3ad6d95cf3c87bae74068038f03b38ce7f66a
194HiAppEvent eventInfo.params.exception={"message":"Unexpected Text in JSON","name":"SyntaxError","stack":"at anonymous (entry/src/main/ets/pages/Index.ets:55:34)"}
195HiAppEvent eventInfo.params.hilog.size=90
196HiAppEvent eventInfo.params.external_log=["/data/storage/el2/log/hiappevent/APP_CRASH_1711440614112_2043.log"]
197HiAppEvent eventInfo.params.log_over_limit=false
198HiAppEvent eventInfo.params.test_data=100
199```
200
201### 移除事件观察者
202
203```ts
204// 移除该应用事件观察者以取消订阅事件
205hiAppEvent.removeWatcher(watcher);
206```
207<!--RP1-->
208<!--RP1End-->
209