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