hiappevent-guidelines.md

# Development of Application Event Logging

## When to Use

The event logging function helps applications log various information generated during running.

## Available APIs

JS application event logging APIs are provided by the **hiAppEvent** module.

The following table provides only a brief description of related APIs. For details, see [HiAppEvent](../reference/apis/js-apis-hiviewdfx-hiappevent.md).

**Table 1** APIs for application event logging

| API                                                      | Description                                                |
| ------------------------------------------------------------ | ---------------------------------------------------- |
| write(AppEventInfo info, AsyncCallback\<void> callback): void | Logs application events in asynchronous mode. This API uses an asynchronous callback to return the result.|
| write(AppEventInfo info): Promise\<void>                     | Logs application events in asynchronous mode. This API uses a promise to return the result. |

**Table 2** APIs for event logging configuration 

| API                              | Description                                                |
| ------------------------------------ | ---------------------------------------------------- |
| configure(ConfigOption config): void | Sets the configuration options for application event logging.|

**Table 3** APIs for watcher management

| API                                            | Description                |
| -------------------------------------------------- | -------------------- |
| addWatcher(Watcher watcher): AppEventPackageHolder | Adds an event watcher.|
| removeWatcher(Watcher watcher): void               | Removes an event watcher.|

**Table 4** APIs for clearing logging data

| API           | Description                |
| ----------------- | -------------------- |
| clearData(): void | Clears local logging data.|

## How to Develop

The following uses a one-time event watcher as an example to illustrate the development procedure.

1. Create an eTS application project. In the displayed **Project** window, choose **entry** > **src** > **main** > **ets** > **pages** > **index.ets**, and double-click **index.ets**. Then, add three buttons to simulate the process of watching for application events. Wherein, button 1 is used to invoke application event logging, button 2 to add an event watcher that automatically triggers a callback, and button 3 to remove the watcher. The complete sample code is as follows:

   ```ts
   import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent';
   
   @Entry
   @Component
   struct Index {
     @State message: string = 'Hello World'
   
     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize(50)
             .fontWeight(FontWeight.Bold)
   
           Button("1 writeTest").onClick(()=>{
             // Perform event logging based on the input event parameters.
             hiAppEvent.write({
               domain: "test_domain",
               name: "test_event",
               eventType: hiAppEvent.EventType.FAULT,
               params: {
                 int_data: 100,
                 str_data: "strValue"
               }
             }).then(() => {
               console.log(`HiAppEvent success to write event`);
             }).catch((err) => {
               console.error(`code: ${err.code}, message: ${err.message}`);
             });
           })
   
           Button("2 addWatcherTest").onClick(()=>{
             // Add an event watcher based on the input subscription parameters.
             hiAppEvent.addWatcher({
               name: "watcher1",
               appEventFilters: [{ domain: "test_domain" }],
               triggerCondition: {
                 row: 2,
                 size: 1000,
                 timeOut: 2
               },
               onTrigger: function (curRow, curSize, holder) {
                 // If the holder object is null, return an error after recording it in the log.
                 if (holder == null) {
                   console.error("HiAppEvent holder is null");
                   return;
                 }
                 // Set the size threshold to 1,000 bytes for obtaining an event package.
                 holder.setSize(1000);
                 let eventPkg = null;
                 // Obtain the event package based on the configured size threshold. If returned event package is null, all event data has been obtained.
                 while ((eventPkg = holder.takeNext()) != null) {
                   // Parse the obtained event package and display the result on the Log page.
                   console.info(`HiAppEvent eventPkg.packageId=${eventPkg.packageId}`);
                   console.info(`HiAppEvent eventPkg.row=${eventPkg.row}`);
                   console.info(`HiAppEvent eventPkg.size=${eventPkg.size}`);
                   // Traverse and parse event string arrays in the obtained event package.
                   for (const eventInfo of eventPkg.data) {
                     console.info(`HiAppEvent eventPkg.data=${eventInfo}`);
                   }
                 }
               }
             });
           })
   
           Button("3 removeWatcherTest").onClick(()=>{
             // Remove the specified event watcher.
             hiAppEvent.removeWatcher({
               name: "watcher1"
             })
           })
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   ```

2. Touch the run button on the IDE to run the project.

3. Touch button 1 on the application UI to start application event logging. If the logging is successful, you'll see the following message in the **Log** window:

   ```
   success to write event: 0
   ```

4. On the application UI, touch button 2 to add an event watcher, and touch button 1 for multiple times to perform application event logging. If any callback trigger condition (event count, event data size, and timeout duration) is met, the event watcher will invoke a callback and the event package obtained through the callback will be displayed in the **Log** window.

   ```
   HiAppEvent eventPkg.packageId=0
   HiAppEvent eventPkg.row=2
   HiAppEvent eventPkg.size=308
   HiAppEvent eventPkg.data={"domain_":"test_domain","name_":"test_event","type_":1,"time_":1502096107556,"tz_":"+0000","pid_":4204,"tid_":4223,"int_data":100,"str_data":"strValue"}
   ```

5. On the application UI, touch button 3 to remove the event watcher. Then, touch button 1 for multiple times to perform application event logging. In such a case, there will be no log information about the callback invoked by the event watcher.

## Samples

The following sample is provided to help you better understand how to develop the application event logging feature:

- [`JsDotTest`: Event Logging (JS) (API8)](https://gitee.com/openharmony/applications_app_samples/tree/master/DFX/JsDotTest)