Subscribing to Main Thread Jank Events (ArkTS)

Main Thread Jank Event Specifications

For details, see Main Thread Jank Event Overview.

Available APIs

For details about how to use the APIs, see Application Event Logging.

API	Description
addWatcher(watcher: Watcher): AppEventPackageHolder	Adds a watcher to listen for application events.
removeWatcher(watcher: Watcher): void	Removes a watcher to unsubscribe from application events.

How to Develop

The following describes how to subscribe to the main thread jank event in sampling stack, which is reported when a task running in the main thread times out.

1. Create an ArkTS application project. In the entry/src/main/ets/entryability/EntryAbility.ets file, import the dependent modules.

   import { hiAppEvent, hilog } from '@kit.PerformanceAnalysisKit';
   

2. 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:

    hiAppEvent.addWatcher({
      // Set the watcher name. The system identifies different watchers based on their names.
      name: "watcher",
      // Add the system events to watch, for example, the main thread jank event.
      appEventFilters: [
        {
          domain: hiAppEvent.domain.OS,
          names: [hiAppEvent.event.MAIN_THREAD_JANK]
        }
      ],
      // Implement a callback for the registered system event so that you can apply custom processing to the event data obtained.
      onReceive: (domain: string, appEventGroups: Array<hiAppEvent.AppEventGroup>) => {
        hilog.info(0x0000, 'testTag', `HiAppEvent onReceive: domain=${domain}`);
        for (const eventGroup of appEventGroups) {
          // The event name uniquely identifies a system event.
          hilog.info(0x0000, 'testTag', `HiAppEvent eventName=${eventGroup.name}`);
          for (const eventInfo of eventGroup.appEventInfos) {
            // Apply custom processing to the event data obtained, for example, print the event data in the log.
            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.domain=${eventInfo.domain}`);
            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.name=${eventInfo.name}`);
            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.eventType=${eventInfo.eventType}`);
            // Obtain the timestamp when the main thread jank event occurs.
            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.time=${eventInfo.params['time']}`);
            // Obtain the version information of the application.
            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.bundle_version=${eventInfo.params['bundle_version']}`);
            // Obtain the bundle name of the application.
            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.bundle_name=${eventInfo.params['bundle_name']}`);
            // Obtain the PID and UID of the application.
            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.pid=${eventInfo.params['pid']}`);
            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.uid=${eventInfo.params['uid']}`);
            // Obtain the begin time and end time on the main thread.
            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.begin_time=${eventInfo.params['begin_time']}`);
            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.end_time=${eventInfo.params['end_time']}`);
            // Obtain the error log file generated when the main thread jank event occurs.
            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.external_log=${JSON.stringify(eventInfo.params['external_log'])}`);
            hilog.info(0x0000, 'testTag', `HiAppEvent eventInfo.params.log_over_limit=${eventInfo.params['log_over_limit']}`);
          }
        }
      }
    });
   

3. In the entry > src > main > ets > pages> Index.ets file, add the timeOut500 button with onClick() to trigger a main thread jank event when the button is clicked. The sample code is as follows:.

    Button("timeOut350")
    .fontSize(50)
               .fontWeight(FontWeight.Bold)
               .onClick(() => {
                 let t = Date.now();
                 while (Date.now() - t <= 350) {}
               })
   

4. In DevEco Studio, click the Run button to run the application project. Click the timeOut350 button twice consecutively to trigger a main thread jank event.

5. After the main thread jank event is reported, the system calls onReceive(). You can view the following event information in the Log window.

   Tracing data of the main thread jank event is as follows:

    HiAppEvent eventInfo.domain=OS
    HiAppEvent eventInfo.name=MAIN_THREAD_JANK
    HiAppEvent eventInfo.eventType=1
    HiAppEvent eventInfo.params.time=1717593620518
    HiAppEvent eventInfo.params.bundle_version=1.0.0
    HiAppEvent eventInfo.params.bundle_name=com.example.main_thread_jank
    HiAppEvent eventInfo.params.pid=40986
    HiAppEvent eventInfo.params.uid=20020150
    HiAppEvent eventInfo.params.begin_time=1717593620016
    HiAppEvent eventInfo.params.end_time=1717593620518
    HiAppEvent eventInfo.params.external_log=["/data/storage/el2/log/watchdog/MAIN_THREAD_JANK_20240613211739_40986.txt"]
    HiAppEvent eventInfo.params.log_over_limit=false
   

   The sampling stack of the main thread jank event is similar to the trace result. The differences are as follows:

   Stack: external_log=["/data/storage/el2/log/watchdog/MAIN_THREAD_JANK_yyyyMMDDHHmmss_xxxx.txt"]. xxxx indicates the process ID.

   Trace: external_log=[""/data/storage/el2/log/watchdog/MAIN_THREAD_JANK_unix timestamp_xxxx.trace"]. xxxx indicates the process ID.