1# @ohos.hiAppEvent (Application Event Logging)
2
3The **hiAppEvent** module provides the application event logging functions, such as writing application events to the event file and managing the event logging configuration.
4
5> **NOTE**
6>
7> - The APIs provided by this module are deprecated since API version 9. You are advised to use [`@ohos.hiviewdfx.hiAppEvent`](js-apis-hiviewdfx-hiappevent.md).
8> - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
9
10
11## Modules to Import
12
13```ts
14import hiAppEvent from '@ohos.hiAppEvent';
15```
16
17## How to Use
18
19Before using application event logging, you need to understand the requirements for related parameters.
20
21**Event Name**
22
23An event name is a string that contains a maximum of 48 characters, including the dollar sign ($), digits (0 to 9), letters (a to z), and underscore (_). It must start with a letter or dollar sign ($) and end with a digit or letter.
24
25**Event Type**
26
27An event type is an enumerated value of [EventType](#eventtype).
28
29**Event Parameter**
30
31An event parameter is an object in key-value pair format, where the key is the parameter name and the value is the parameter value. The requirements are as follows:
32
33- A parameter name is a string that contains a maximum of 32 characters, including the dollar sign ($), digits (0 to 9), letters (a to z), and underscore (_). It must start with a letter or dollar sign ($) and end with a digit or letter.
34- A parameter value can be of the string, number, boolean, or array type.
35- If the parameter value is a string, its maximum length is 8*1024 characters. If this limit is exceeded, excess characters will be discarded.
36- If the parameter value is a number, the value must be within the range of **Number.MIN_SAFE_INTEGER** to **Number.MAX_SAFE_INTEGER**. Otherwise, uncertain values may be generated.
37- If the parameter value is an array, the elements in the array must be of the same type, which can only be string, number, or boolean. In addition, the number of elements must be less than 100. If this limit is exceeded, excess elements will be discarded.
38- The maximum number of parameters is 32. If this limit is exceeded, excess parameters will be discarded.
39
40**Event Callback**
41
42Event callback can be a callback or promise that carries the return value obtained by invoking the event logging API. You can add the processing of the return value in the event callback as follows:
43
44- If the return value is **0**, the event verification is successful, and the event will be directly written to the event file.
45- If the return value is greater than **0**, invalid parameters are present in the event, and the event will be written to the event file after the invalid parameters are ignored.
46- If the return value is smaller than **0**, the event parameter verification fails, and the event will not be written to the event file.
47
48## hiAppEvent.write
49
50write(eventName: string, eventType: EventType, keyValues: object, callback: AsyncCallback<void>): void
51
52Writes event information to the event file of the current day. This API uses an asynchronous callback to return the result.
53
54**System capability**: SystemCapability.HiviewDFX.HiAppEvent
55
56**Parameters**
57
58| Name   | Type                     | Mandatory | Description          |
59| --------- | ------------------------- | ---- | -------------- |
60| eventName | string                    | Yes  | Event name.    |
61| eventType | [EventType](#eventtype)   | Yes  | Event type.    |
62| keyValues | object                    | Yes  | Event parameters.    |
63| callback  | AsyncCallback<void> | Yes  | Event callback. |
64
65**Example**
66
67```ts
68import { BusinessError } from '@ohos.base'
69
70let eventParams: Record<string, number | string> = {
71  "int_data": 100,
72  "str_data": "strValue",
73};
74hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, eventParams, (err: BusinessError) => {
75  if (err) {
76    // Event writing error: Write the event to the event file after the invalid parameters in the event are ignored, or stop writing the event if the event verification fails.
77    console.error(`failed to write event, code=${err.code}`);
78    return;
79  }
80  // Event writing success
81  console.log(`success to write event`);
82});
83```
84
85
86## hiAppEvent.write
87
88write(eventName: string, eventType: EventType, keyValues: object): Promise&lt;void&gt;
89
90Writes event information to the event file of the current day. This API uses a promise to return the result.
91
92**System capability**: SystemCapability.HiviewDFX.HiAppEvent
93
94**Parameters**
95
96| Name   | Type                   | Mandatory | Description      |
97| --------- | ----------------------- | ---- | ---------- |
98| eventName | string                  | Yes  | Event name. |
99| eventType | [EventType](#eventtype) | Yes  | Event type. |
100| keyValues | object                  | Yes  | Event parameters. |
101
102**Return value**
103
104| Type               | Description                                                        |
105| ------------------- | ------------------------------------------------------------ |
106| Promise&lt;void&gt; | Promise used to asynchronously process the callback in the **then()** and **catch()** methods when event writing succeeded or failed. |
107
108**Example**
109
110```ts
111import { BusinessError } from '@ohos.base'
112
113let eventParams: Record<string, number | string> = {
114  "int_data": 100,
115  "str_data": "strValue",
116};
117hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, eventParams).then(() => {
118  // Event writing success
119  console.log(`success to write event`);
120}).catch((err: BusinessError) => {
121  // Event writing error: Write the event to the event file after the invalid parameters in the event are ignored, or stop writing the event if the event verification fails.
122  console.error(`failed to write event, code=${err.code}`);
123});
124```
125
126## hiAppEvent.configure
127
128configure(config: ConfigOption): boolean
129
130Configures the application event logging function, such as setting the event logging switch and maximum size of the directory that stores the event logging files.
131
132**System capability**: SystemCapability.HiviewDFX.HiAppEvent
133
134**Parameters**
135
136| Name | Type                         | Mandatory | Description                    |
137| ------ | ----------------------------- | ---- | ------------------------ |
138| config | [ConfigOption](#configoption) | Yes  | Configuration items for application event logging. |
139
140**Return value**
141
142| Type   | Description                                                       |
143| ------- | ----------------------------------------------------------- |
144| boolean | Returns **true** if the configuration is successful; returns **false** otherwise. |
145
146**Example**
147
148```ts
149// Set the application event logging switch.
150let config1: hiAppEvent.ConfigOption = {
151  disable: true,
152};
153hiAppEvent.configure(config1);
154
155// Configure the maximum size of the directory that stores the event logging files.
156let config2: hiAppEvent.ConfigOption = {
157  maxStorage: '100M',
158};
159hiAppEvent.configure(config2);
160```
161
162## ConfigOption
163
164Provides the configuration items for application event logging.
165
166**System capability**: SystemCapability.HiviewDFX.HiAppEvent
167
168| Name      | Type   | Mandatory | Description                                                        |
169| ---------- | ------- | ---- | ------------------------------------------------------------ |
170| disable    | boolean | No  | Application event logging switch. The value **true** means to disable the application event logging function, and the value **false** means the opposite. |
171| maxStorage | string  | No  | Maximum size of the event file storage directory. The default value is **10M**. If the specified size is exceeded, the oldest event logging files in the directory will be deleted to free up space. |
172
173
174## EventType
175
176Enumerates the event types.
177
178**System capability**: SystemCapability.HiviewDFX.HiAppEvent
179
180| Name     | Value  | Description          |
181| --------- | ---- | -------------- |
182| FAULT     | 1    | Fault event. |
183| STATISTIC | 2    | Statistical event. |
184| SECURITY  | 3    | Security event. |
185| BEHAVIOR  | 4    | Behavior event. |
186
187
188## Event
189
190Provides constants that define the names of all predefined events.
191
192**System capability**: SystemCapability.HiviewDFX.HiAppEvent
193
194| Name                     | Type  | Readable | Writable | Description                |
195| ------------------------- | ------ | ---- | ---- | -------------------- |
196| USER_LOGIN                | string | Yes  | No  | User login event.      |
197| USER_LOGOUT               | string | Yes  | No  | User logout event.      |
198| DISTRIBUTED_SERVICE_START | string | Yes  | No  | Distributed service startup event. |
199
200
201## Param
202
203Provides constants that define the names of all predefined event parameters.
204
205**System capability**: SystemCapability.HiviewDFX.HiAppEvent
206
207| Name                           | Type  | Readable | Writable | Description              |
208| ------------------------------- | ------ | ---- | ---- | ------------------ |
209| USER_ID                         | string | Yes  | No  | Custom user ID.    |
210| DISTRIBUTED_SERVICE_NAME        | string | Yes  | No  | Distributed service name.  |
211| DISTRIBUTED_SERVICE_INSTANCE_ID | string | Yes  | No  | Distributed service instance ID. |
212