1# Subscribing to Freeze 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**API for Setting Custom Event Parameters**
8
9| API                                             | Description                                        |
10| --------------------------------------------------- | -------------------------------------------- |
11| setEventParam(params: Record<string, ParamType>, domain: string, name?: string): Promise<void> | Sets custom event parameters.|
12
13**Subscription APIs**
14
15| API                                             | Description                                        |
16| --------------------------------------------------- | -------------------------------------------- |
17| addWatcher(watcher: Watcher): AppEventPackageHolder | Adds a watcher to listen for application events.|
18| removeWatcher(watcher: Watcher): void               | Removes a watcher to unsubscribe from application events.|
19
20## How to Develop
21
22The following describes how to subscribe to the freeze event triggered by a button click.
23
241. Create an ArkTS application project. In the **entry/src/main/ets/entryability/EntryAbility.ets** file, import the dependent modules.
25
26   ```ts
27   import { BusinessError } from '@kit.BasicServicesKit';
28   import { hiAppEvent, hilog } from '@kit.PerformanceAnalysisKit';
29   ```
30
312. In the **entry/src/main/ets/entryability/EntryAbility.ets** file, set the custom parameters in **onCreate()**. The sample code is as follows:
32
33   ```ts
34    // Assign a value to params, which is a key-value pair.
35    let params: Record<string, hiAppEvent.ParamType> = {
36      "test_data": 100,
37    };
38    // Set custom parameters for the freeze event.
39    hiAppEvent.setEventParam(params, hiAppEvent.domain.OS, hiAppEvent.event.APP_FREEZE).then(() => {
40      hilog.info(0x0000, 'testTag', `HiAppEvent success to set svent param`);
41    }).catch((err: BusinessError) => {
42      hilog.error(0x0000, 'testTag', `HiAppEvent code: ${err.code}, message: ${err.message}`);
43    });
44   ```
45
463. 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:
47
48   ```ts
49    hiAppEvent.addWatcher({
50      // Set the watcher name. The system identifies different watchers based on their names.
51      name: "watcher",
52      // Add the system events to watch, for example, freeze events.
53      appEventFilters: [
54        {
55          domain: hiAppEvent.domain.OS,
56          names: [hiAppEvent.event.APP_FREEZE]
57        }
58      ],
59      // Implement a callback for the registered system event so that you can apply custom processing to the event data obtained.
60      onReceive: (domain: string, appEventGroups: Array<hiAppEvent.AppEventGroup>) => {
61        hilog.info(0x0000, 'testTag', `HiAppEvent onReceive: domain=${domain}`);
62        for (const eventGroup of appEventGroups) {
63          // The event name uniquely identifies a system event.
64          hilog.info(0x0000, 'testTag', `HiAppEvent eventName=${eventGroup.name}`);
65          for (const eventInfo of eventGroup.appEventInfos) {
66            // Apply custom processing to the event data obtained, for example, print the event data in the log.
67            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.domain=${eventInfo.domain}`);
68            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.name=${eventInfo.name}`);
69            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.eventType=${eventInfo.eventType}`);
70            // Obtain the timestamp of the freeze event.
71            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.time=${eventInfo.params['time']}`);
72            // Obtain the foreground and background status of the application when the freeze event occurs.
73            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.foreground=${eventInfo.params['foreground']}`);
74            // Obtain the version information of the application.
75            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.bundle_version=${eventInfo.params['bundle_version']}`);
76            // Obtain the bundle name of the application.
77            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.bundle_name=${eventInfo.params['bundle_name']}`);
78            // Obtain the process name of the application.
79            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.process_name=${eventInfo.params['process_name']}`);
80            // Obtain the process ID of the application.
81            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.pid=${eventInfo.params['pid']}`);
82            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.uid=${eventInfo.params['uid']}`);
83            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.uuid=${eventInfo.params['uuid']}`);
84            // Obtain the exception type and cause of the freeze event.
85            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.exception=${JSON.stringify(eventInfo.params['exception'])}`);
86            // Obtain the log information when the freeze event occurs.
87            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.hilog.size=${eventInfo.params['hilog'].length}`);
88            // Obtain the messages that are not yet processed by the main thread when the freeze event occurs.
89            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.event_handler.size=${eventInfo.params['event_handler'].length}`);
90            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.event_handler_size_3s=${eventInfo.params['event_handler_size_3s']}`);
91            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.event_handler_size_6s=${eventInfo.params['event_handler_size_6s']}`);
92            // Obtain the synchronous binder call information when the freeze event occurs.
93            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.peer_binder.size=${eventInfo.params['peer_binder'].length}`);
94            // Obtain the full thread call stack when the freeze event occurs.
95            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.threads.size=${eventInfo.params['threads'].length}`);
96            // Obtain the memory information when the freeze event occurs.
97            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.memory=${JSON.stringify(eventInfo.params['memory'])}`);
98            // Obtain the error log file when the freeze event occurs.
99            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.external_log=${JSON.stringify(eventInfo.params['external_log'])}`);
100            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.log_over_limit=${eventInfo.params['log_over_limit']}`);
101            // Obtain the custom test_data of the freeze event.
102            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.test_data=${eventInfo.params['test_data']}`);
103          }
104        }
105      }
106    });
107   ```
108
1094. In the **entry/src/main/ets/pages/index.ets** file, add the **appFreeze** button and construct a scenario for triggering a freeze event in **onClick()**. The sample code is as follows:
110
111   ```ts
112    Button("appFreeze").onClick(()=>{
113      // Construct a scenario in onClick() for triggering a freeze event.
114      setTimeout(() => {
115        while (true) {}
116      }, 1000)
117    })
118   ```
119
1205. In DevEco Studio, click the **Run** button to run the project. Then, click the **appfreeze** button to trigger a freeze event.
121
1226. The application crashes. After restarting the application, you can view the following event information in the **Log** window.
123
124   ```text
125   HiAppEvent onReceive: domain=OS
126   HiAppEvent eventName=APP_FREEZE
127   HiAppEvent eventInfo.domain=OS
128   HiAppEvent eventInfo.name=APP_FREEZE
129   HiAppEvent eventInfo.eventType=1
130   HiAppEvent eventInfo.params.time=1711440881768
131   HiAppEvent eventInfo.params.foreground=true
132   HiAppEvent eventInfo.params.bundle_version=1.0.0
133   HiAppEvent eventInfo.params.bundle_name=com.example.myapplication
134   HiAppEvent eventInfo.params.process_name=com.example.myapplication
135   HiAppEvent eventInfo.params.pid=3197
136   HiAppEvent eventInfo.params.uid=20010043
137   HiAppEvent eventInfo.params.uuid=27fac7098da46efe1cae9904946ec06c5acc91689c365efeefb7a23a0c37df77
138   HiAppEvent eventInfo.params.exception={"message":"App main thread is not response!","name":"THREAD_BLOCK_6S"}
139   HiAppEvent eventInfo.params.hilog.size=77
140   HiAppEvent eventInfo.params.event_handler.size=6
141   HiAppEvent eventInfo.params.event_handler_size_3s=5
142   HiAppEvent eventInfo.params.event_handler_size_6s=6
143   HiAppEvent eventInfo.params.peer_binder.size=0
144   HiAppEvent eventInfo.params.threads.size=28
145   HiAppEvent eventInfo.params.memory={"pss":0,"rss":0,"sys_avail_mem":1361464,"sys_free_mem":796232,"sys_total_mem":1992340,"vss":0}
146   HiAppEvent eventInfo.params.external_log=["/data/storage/el2/log/hiappevent/APP_FREEZE_1711440899240_3197.log"]
147   HiAppEvent eventInfo.params.log_over_limit=false
148   HiAppEvent eventInfo.params.test_data=100
149   ```
150