• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.hiviewdfx.hiAppEvent (应用事件打点)
2
3本模块提供了应用事件打点能力，包括应用事件落盘、应用事件订阅、应用事件清理、打点功能配置等功能。
4
5> **说明：**
6>
7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8
9
10## 导入模块
11
12```js
13import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent';
14```
15
16## hiAppEvent.write
17
18write(info: [AppEventInfo](#appeventinfo), callback: AsyncCallback<void>): void
19
20应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo)类型的事件对象，使用callback方式作为异步回调。
21
22**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
23
24**参数：**
25
26| 参数名   | 类型                           | 必填 | 说明           |
27| -------- | ------------------------------ | ---- | -------------- |
28| info     | [AppEventInfo](#appeventinfo) | 是   | 应用事件对象。 |
29| callback | AsyncCallback<void>      | 是   | 打点回调函数。 |
30
31**错误码：**
32
33以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errorcode-hiappevent.md)。
34
35| 错误码ID | 错误信息                                      |
36| -------- | --------------------------------------------- |
37| 11100001 | Function is disabled.                         |
38| 11101001 | Invalid event domain.                         |
39| 11101002 | Invalid event name.                           |
40| 11101003 | Invalid number of event parameters.           |
41| 11101004 | Invalid string length of the event parameter. |
42| 11101005 | Invalid event parameter name.                 |
43| 11101006 | Invalid array length of the event parameter.  |
44
45**示例：**
46
47```js
48hiAppEvent.write({
49    domain: "test_domain",
50    name: "test_event",
51    eventType: hiAppEvent.EventType.FAULT,
52    params: {
53        int_data: 100,
54        str_data: "strValue"
55    }
56}, (err) => {
57    if (err) {
58        console.error(`code: ${err.code}, message: ${err.message}`);
59        return;
60    }
61    console.log(`success to write event`);
62});
63```
64
65## hiAppEvent.write
66
67write(info: [AppEventInfo](#appeventinfo)): Promise<void>
68
69应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo)类型的事件对象，使用Promise方式作为异步回调。
70
71**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
72
73**参数：**
74
75| 参数名 | 类型                           | 必填 | 说明           |
76| ------ | ------------------------------ | ---- | -------------- |
77| info   | [AppEventInfo](#appeventinfo) | 是   | 应用事件对象。 |
78
79**返回值：**
80
81| 类型                | 说明          |
82| ------------------- | ------------- |
83| Promise<void> | Promise对象。 |
84
85**错误码：**
86
87以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errorcode-hiappevent.md)。
88
89| 错误码ID | 错误信息                                      |
90| -------- | --------------------------------------------- |
91| 11100001 | Function is disabled.                         |
92| 11101001 | Invalid event domain.                         |
93| 11101002 | Invalid event name.                           |
94| 11101003 | Invalid number of event parameters.           |
95| 11101004 | Invalid string length of the event parameter. |
96| 11101005 | Invalid event parameter name.                 |
97| 11101006 | Invalid array length of the event parameter.  |
98
99**示例：**
100
101```js
102hiAppEvent.write({
103    domain: "test_domain",
104    name: "test_event",
105    eventType: hiAppEvent.EventType.FAULT,
106    params: {
107        int_data: 100,
108        str_data: "strValue"
109    }
110}).then(() => {
111    console.log(`success to write event`);
112}).catch((err) => {
113    console.error(`code: ${err.code}, message: ${err.message}`);
114});
115```
116
117## AppEventInfo
118
119此接口提供了应用事件信息的参数选项。
120
121**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
122
123| 名称      | 类型                    | 必填 | 说明                                                         |
124| --------- | ----------------------- | ---- | ------------------------------------------------------------ |
125| domain    | string                  | 是   | 事件领域。事件领域名称支持数字、小写字母、下划线字符，需要以小写字母开头且不能以下划线结尾，长度非空且不超过32个字符。 |
126| name      | string                  | 是   | 事件名称。事件名称支持数字、小写字母、下划线字符，需要以小写字母开头且不能以下划线结尾，长度非空且不超过48个字符。 |
127| eventType | [EventType](#eventtype) | 是   | 事件类型。                                                   |
128| params    | object                  | 是   | 事件参数对象，每个事件参数包括参数名和参数值，其规格定义如下：<br>- 参数名为string类型，只支持数字、小写字母、下划线字符，需要以小写字母开头且不能以下划线结尾，长度非空且不超过16个字符。<br>- 参数值支持string、number、boolean、数组类型，string类型参数长度需在8*1024个字符以内，超出会做丢弃处理；number类型参数取值需在Number.MIN_SAFE_INTEGER~Number.MAX_SAFE_INTEGER范围内，超出可能会产生不确定值；数组类型参数中的元素类型只能全为string、number、boolean中的一种，且元素个数需在100以内，超出会做丢弃处理。<br>- 参数个数需在32个以内，超出的参数会做丢弃处理。 |
129
130## hiAppEvent.configure
131
132configure(config: [ConfigOption](configoption)): void
133
134应用事件打点配置方法，可用于配置打点开关、目录存储配额大小等功能。
135
136**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
137
138**参数：**
139
140| 参数名 | 类型                          | 必填 | 说明                     |
141| ------ | ----------------------------- | ---- | ------------------------ |
142| config | [ConfigOption](#configoption) | 是   | 应用事件打点配置项对象。 |
143
144**错误码：**
145
146以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errorcode-hiappevent.md)。
147
148| 错误码ID | 错误信息                         |
149| -------- | -------------------------------- |
150| 11103001 | Invalid max storage quota value. |
151
152**示例：**
153
154```js
155// 配置打点开关为关闭状态
156hiAppEvent.configure({
157    disable: true
158});
159
160// 配置文件目录存储配额为100M
161hiAppEvent.configure({
162    maxStorage: '100M'
163});
164```
165
166## ConfigOption
167
168此接口提供了对应用事件打点功能的配置选项。
169
170**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
171
172| 名称       | 类型    | 必填 | 说明                                                         |
173| ---------- | ------- | ---- | ------------------------------------------------------------ |
174| disable    | boolean | 否   | 打点功能开关，默认值为false。true：关闭打点功能，false：不关闭打点功能。 |
175| maxStorage | string  | 否   | 打点数据存放目录的配额大小，默认值为“10M”。<br>在目录大小超出配额后，下次打点会触发对目录的清理操作：按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出配额时结束。 |
176
177## hiAppEvent.addWatcher
178
179addWatcher(watcher: [Watcher](#watcher)): [AppEventPackageHolder](#appeventpackageholder)
180
181添加应用事件观察者方法，可用于订阅应用事件。
182
183**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
184
185**参数：**
186
187| 参数名  | 类型                 | 必填 | 说明             |
188| ------- | -------------------- | ---- | ---------------- |
189| watcher | [Watcher](#watcher) | 是   | 应用事件观察者。 |
190
191**返回值：**
192
193| 类型                                             | 说明                                 |
194| ------------------------------------------------ | ------------------------------------ |
195| [AppEventPackageHolder](#appeventpackageholder) | 订阅数据持有者，订阅失败时返回null。 |
196
197**错误码：**
198
199以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errorcode-hiappevent.md)。
200
201| 错误码ID | 错误信息                        |
202| -------- | ------------------------------- |
203| 11102001 | Invalid watcher name.           |
204| 11102002 | Invalid filtering event domain. |
205| 11102003 | Invalid row value.              |
206| 11102004 | Invalid size value.             |
207| 11102005 | Invalid timeout value.          |
208
209**示例：**
210
211```js
212// 1. 如果观察者传入了回调的相关参数，则可以选择在自动触发的回调函数中对订阅事件进行处理
213hiAppEvent.addWatcher({
214    name: "watcher1",
215    appEventFilters: [
216        {
217            domain: "test_domain",
218            eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR]
219        }
220    ],
221    triggerCondition: {
222        row: 10,
223        size: 1000,
224        timeOut: 1
225    },
226    onTrigger: function (curRow, curSize, holder) {
227        if (holder == null) {
228            console.error("holder is null");
229            return;
230        }
231        let eventPkg = null;
232        while ((eventPkg = holder.takeNext()) != null) {
233            console.info(`eventPkg.packageId=${eventPkg.packageId}`);
234            console.info(`eventPkg.row=${eventPkg.row}`);
235            console.info(`eventPkg.size=${eventPkg.size}`);
236            for (const eventInfo of eventPkg.data) {
237                console.info(`eventPkg.data=${eventInfo}`);
238            }
239        }
240    }
241});
242
243// 2. 如果观察者未传入回调的相关参数，则可以选择使用返回的holder对象手动去处理订阅事件
244let holder = hiAppEvent.addWatcher({
245    name: "watcher2",
246});
247if (holder != null) {
248    let eventPkg = null;
249    while ((eventPkg = holder.takeNext()) != null) {
250        console.info(`eventPkg.packageId=${eventPkg.packageId}`);
251        console.info(`eventPkg.row=${eventPkg.row}`);
252        console.info(`eventPkg.size=${eventPkg.size}`);
253        for (const eventInfo of eventPkg.data) {
254            console.info(`eventPkg.data=${eventInfo}`);
255        }
256    }
257}
258```
259
260## hiAppEvent.removeWatcher
261
262removeWatcher(watcher: [Watcher](#watcher)): void
263
264移除应用事件观察者方法，可用于取消订阅应用事件。
265
266**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
267
268**参数：**
269
270| 参数名  | 类型                 | 必填 | 说明             |
271| ------- | -------------------- | ---- | ---------------- |
272| watcher | [Watcher](#watcher) | 是   | 应用事件观察者。 |
273
274**错误码：**
275
276以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errorcode-hiappevent.md)。
277
278| 错误码ID | 错误信息              |
279| -------- | --------------------- |
280| 11102001 | Invalid watcher name. |
281
282**示例：**
283
284```js
285// 1. 定义一个应用事件观察者
286let watcher = {
287    name: "watcher1",
288}
289
290// 2. 添加一个应用事件观察者来订阅事件
291hiAppEvent.addWatcher(watcher);
292
293// 3. 移除该应用事件观察者以取消订阅事件
294hiAppEvent.removeWatcher(watcher);
295```
296
297## Watcher
298
299此接口提供了应用事件观察者的参数选项。
300
301**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
302
303| 名称             | 类型                                                         | 必填 | 说明                                                         |
304| ---------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
305| name             | string                                                       | 是   | 观察者名称，用于唯一标识观察者。                             |
306| triggerCondition | [TriggerCondition](#triggercondition)                        | 否   | 订阅回调触发条件，需要与回调函数一同传入才会生效。           |
307| appEventFilters  | [AppEventFilter](#appeventfilter)[]                          | 否   | 订阅过滤条件，在需要对订阅事件进行过滤时传入。               |
308| onTrigger        | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder)) => void | 否   | 订阅回调函数，需要与回调触发条件一同传入才会生效，函数入参说明如下：<br>curRow：在本次回调触发时的订阅事件总数量； <br>curSize：在本次回调触发时的订阅事件总大小，单位为byte；  <br/>holder：订阅数据持有者对象，可以通过其对订阅事件进行处理。 |
309
310## TriggerCondition
311
312此接口提供了回调触发条件的参数选项，只要满足任一条件就会触发订阅回调。
313
314**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
315
316| 名称    | 类型   | 必填 | 说明                                   |
317| ------- | ------ | ---- | -------------------------------------- |
318| row     | number | 否   | 满足触发回调的事件总数量。             |
319| size    | number | 否   | 满足触发回调的事件总大小，单位为byte。 |
320| timeOut | number | 否   | 满足触发回调的超时时长，单位为30s。    |
321
322## AppEventFilter
323
324此接口提供了过滤应用事件的参数选项。
325
326**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
327
328| 名称       | 类型                      | 必填 | 说明                     |
329| ---------- | ------------------------- | ---- | ------------------------ |
330| domain     | string                    | 是   | 需要订阅的事件领域。     |
331| eventTypes | [EventType](#eventtype)[] | 否   | 需要订阅的事件类型集合。 |
332
333## AppEventPackageHolder
334
335订阅数据持有者类，用于对订阅事件进行处理。
336
337**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
338
339### constructor
340
341constructor(watcherName: string)
342
343类构造函数，在添加应用事件观察者时，会由系统自动调用来创建一个该观察者对应的订阅数据持有者对象，并返回给开发者。
344
345**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
346
347**参数：**
348
349| 参数名 | 类型              | 必填 | 说明                     |
350| ------ | ----------------- | ---- | ------------------------ |
351| watcherName | string | 是   | 观察者名称。 |
352
353**示例：**
354
355```js
356let holder = hiAppEvent.addWatcher({
357    name: "watcher",
358});
359```
360
361### setSize
362
363setSize(size: number): void
364
365设置每次取出的应用事件包的数据大小阈值。
366
367**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
368
369**参数：**
370
371| 参数名 | 类型   | 必填 | 说明                                         |
372| ------ | ------ | ---- | -------------------------------------------- |
373| size   | number | 是   | 数据大小阈值，单位为byte，默认值为512*1024。 |
374
375**错误码：**
376
377以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errorcode-hiappevent.md)。
378
379| 错误码ID | 错误信息            |
380| -------- | ------------------- |
381| 11104001 | Invalid size value. |
382
383**示例：**
384
385```js
386let holder = hiAppEvent.addWatcher({
387    name: "watcher",
388});
389holder.setSize(1000);
390```
391
392### takeNext
393
394takeNext(): [AppEventPackage](#appeventpackage)
395
396根据设置的数据大小阈值来取出订阅事件数据，当订阅事件数据全部被取出时返回null作为标识。
397
398**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
399
400**示例：**
401
402```js
403let holder = hiAppEvent.addWatcher({
404    name: "watcher",
405});
406let eventPkg = holder.takeNext();
407```
408
409## AppEventPackage
410
411此接口提供了订阅返回的应用事件包的参数定义。
412
413**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
414
415| 名称      | 类型     | 必填 | 说明                           |
416| --------- | -------- | ---- | ------------------------------ |
417| packageId | number   | 是   | 事件包ID，从0开始自动递增。    |
418| row       | number   | 是   | 事件包的事件数量。             |
419| size      | number   | 是   | 事件包的事件大小，单位为byte。 |
420| data      | string[] | 是   | 事件包的事件信息。             |
421
422## hiAppEvent.clearData
423
424clearData(): void
425
426应用事件打点数据清理方法，将应用存储在本地的打点数据进行清除。
427
428**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
429
430**示例：**
431
432```js
433hiAppEvent.clearData();
434```
435
436
437## EventType
438
439事件类型枚举。
440
441**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
442
443| 名称      | 值   | 说明           |
444| --------- | ---- | -------------- |
445| FAULT     | 1    | 故障类型事件。 |
446| STATISTIC | 2    | 统计类型事件。 |
447| SECURITY  | 3    | 安全类型事件。 |
448| BEHAVIOR  | 4    | 行为类型事件。 |
449
450
451## event
452
453此接口提供了所有预定义事件的事件名称常量。
454
455**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
456
457| 名称                      | 类型   | 说明                 |
458| ------------------------- | ------ | -------------------- |
459| USER_LOGIN                | string | 用户登录事件。       |
460| USER_LOGOUT               | string | 用户登出事件。       |
461| DISTRIBUTED_SERVICE_START | string | 分布式服务启动事件。 |
462
463
464## param
465
466此接口提供了所有预定义参数的参数名称常量。
467
468**系统能力：** SystemCapability.HiviewDFX.HiAppEvent
469
470| 名称                            | 类型   | 说明               |
471| ------------------------------- | ------ | ------------------ |
472| USER_ID                         | string | 用户自定义ID。     |
473| DISTRIBUTED_SERVICE_NAME        | string | 分布式服务名称。   |
474| DISTRIBUTED_SERVICE_INSTANCE_ID | string | 分布式服务实例ID。 |