1# Subscribing to Crash Events (ArkTS)
2
3## Available APIs
4
5For details about how to use the APIs (such as parameter usage constraints and value ranges), see [Application Event Logging](../reference/apis-performance-analysis-kit/js-apis-hiviewdfx-hiappevent.md).
6
7> **NOTE**
8>
9> The ArkTS APIs can be used to subscribe to JsError and NativeCrash events.
10
11**API for Setting Custom Event Parameters**
12
13| API                                             | Description                                        |
14| --------------------------------------------------- | -------------------------------------------- |
15| setEventParam(params: Record<string, ParamType>, domain: string, name?: string): Promise<void> | Sets custom event parameters.|
16
17**Subscription APIs**
18
19| API                                             | Description                                        |
20| --------------------------------------------------- | -------------------------------------------- |
21| addWatcher(watcher: Watcher): AppEventPackageHolder | Adds a watcher to listen for application events.|
22| removeWatcher(watcher: Watcher): void               | Removes a watcher to unsubscribe from application events.|
23
24## How to Develop
25
26The following describes how to subscribe to a crash event triggered by a button click.
27
281. Create an ArkTS application project. In the **entry/src/main/ets/entryability/EntryAbility.ets** file, import the dependent modules.
29
30   ```ts
31   import { BusinessError } from '@kit.BasicServicesKit';
32   import { hiAppEvent, hilog } from '@kit.PerformanceAnalysisKit';
33   ```
34
352. In the **entry/src/main/ets/entryability/EntryAbility.ets** file, set the custom parameters in **onCreate()**. The sample code is as follows:
36
37   ```ts
38    // Assign a value to params, which is a key-value pair
39    let params: Record<string, hiAppEvent.ParamType> = {
40      "test_data": 100,
41    };
42    // Set custom parameters for the crash event.
43    hiAppEvent.setEventParam(params, hiAppEvent.domain.OS, hiAppEvent.event.APP_CRASH).then(() => {
44      hilog.info(0x0000, 'testTag', `HiAppEvent success to set svent param`);
45    }).catch((err: BusinessError) => {
46      hilog.error(0x0000, 'testTag', `HiAppEvent code: ${err.code}, message: ${err.message}`);
47    });
48   ```
49
503. In the **entry/src/main/ets/entryability/EntryAbility.ets** file, add a watcher in **onCreate()** to subscribe to system events. The sample code is as follows:
51
52   ```ts
53    hiAppEvent.addWatcher({
54      // Set the watcher name. The system identifies different watchers based on their names.
55      name: "watcher",
56      // Add the system events to watch, for example, crash events.
57      appEventFilters: [
58        {
59          domain: hiAppEvent.domain.OS,
60          names: [hiAppEvent.event.APP_CRASH]
61        }
62      ],
63      // Implement a callback for the registered system event so that you can apply custom processing to the event data obtained.
64      onReceive: (domain: string, appEventGroups: Array<hiAppEvent.AppEventGroup>) => {
65        hilog.info(0x0000, 'testTag', `HiAppEvent onReceive: domain=${domain}`);
66        for (const eventGroup of appEventGroups) {
67          // The event name uniquely identifies a system event.
68          hilog.info(0x0000, 'testTag', `HiAppEvent eventName=${eventGroup.name}`);
69          for (const eventInfo of eventGroup.appEventInfos) {
70            // Apply custom processing to the event data obtained, for example, print the event data in the log.
71            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.domain=${eventInfo.domain}`);
72            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.name=${eventInfo.name}`);
73            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.eventType=${eventInfo.eventType}`);
74            // Obtain the timestamp of the crash event.
75            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.time=${eventInfo.params['time']}`);
76            // Obtain the type of the crash event.
77            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.crash_type=${eventInfo.params['crash_type']}`);
78            // Obtain the foreground and background status of the crashed application.
79            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.foreground=${eventInfo.params['foreground']}`);
80            // Obtain the version information of the crashed application.
81            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.bundle_version=${eventInfo.params['bundle_version']}`);
82            // Obtain the bundle name of the crashed application.
83            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.bundle_name=${eventInfo.params['bundle_name']}`);
84            // Obtain the process ID of the crashed application.
85            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.pid=${eventInfo.params['pid']}`);
86            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.uid=${eventInfo.params['uid']}`);
87            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.uuid=${eventInfo.params['uuid']}`);
88            // Obtain the exception type, cause, and call stack of the crash event.
89            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.exception=${JSON.stringify(eventInfo.params['exception'])}`);
90            // Obtain the log information about the crash event.
91            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.hilog.size=${eventInfo.params['hilog'].length}`);
92            // Obtain the error log file about the crash event.
93            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.external_log=${JSON.stringify(eventInfo.params['external_log'])}`);
94            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.log_over_limit=${eventInfo.params['log_over_limit']}`);
95            // Obtain the custom test_data of the crash event.
96            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.test_data=${eventInfo.params['test_data']}`);
97          }
98        }
99      }
100    });
101   ```
102
1034. In the **entry/src/main/ets/pages/index.ets** file, add the **appCrash** button and construct a scenario for triggering a crash event in **onClick()**. The sample code is as follows:
104
105   ```ts
106    Button("appCrash").onClick(()=>{
107      // Construct a scenario in onClick() to trigger a crash event.
108      let result: object = JSON.parse("");
109    })
110   ```
111
1125. In DevEco Studio, click the **Run** button to run the project. Then, click the **appCrash** button to trigger a crash event. After a crash occurs, the system uses different stack backtracking methods to generate crash logs based on the crash type (JsError or NativeCrash) and then invokes callback. The NativeCrash stack backtracking takes about 2s. In practice, the duration depends on the number of service threads and the duration of inter-process communication. JsError triggers in-process stack backtracking, and NativeCrash triggers out-of-process stack backtracking. Therefore, NativeCrash stack backtracking is more time-consuming than JsError stack backtracking. You can subscribe to crash events so that the stack backtracking result is asynchronously reported without blocking the current service.
113
1146. When the application is restarted, HiAppEvent reports the crash event to the registered watcher. You can view the following event information in the **Log** window.
115
116   ```text
117   HiAppEvent onReceive: domain=OS
118   HiAppEvent eventName=APP_CRASH
119   HiAppEvent eventInfo.domain=OS
120   HiAppEvent eventInfo.name=APP_CRASH
121   HiAppEvent eventInfo.eventType=1
122   HiAppEvent eventInfo.params.time=1711440614001
123   HiAppEvent eventInfo.params.crash_type=JsError
124   HiAppEvent eventInfo.params.foreground=true
125   HiAppEvent eventInfo.params.bundle_version=1.0.0
126   HiAppEvent eventInfo.params.bundle_name=com.example.myapplication
127   HiAppEvent eventInfo.params.pid=2043
128   HiAppEvent eventInfo.params.uid=20010043
129   HiAppEvent eventInfo.params.uuid=b1e953ba0022c112e4502e28e8b3ad6d95cf3c87bae74068038f03b38ce7f66a
130   HiAppEvent eventInfo.params.exception={"message":"Unexpected Text in JSON","name":"SyntaxError","stack":"at anonymous (entry/src/main/ets/pages/Index.ets:55:34)"}
131   HiAppEvent eventInfo.params.hilog.size=90
132   HiAppEvent eventInfo.params.external_log=["/data/storage/el2/log/hiappevent/APP_CRASH_1711440614112_2043.log"]
133   HiAppEvent eventInfo.params.log_over_limit=false
134   HiAppEvent eventInfo.params.test_data=100
135   ```
136
137<!--RP1-->
138<!--RP1End-->
139