harmony 鸿蒙@ohos.hiSysEvent (系统事件打点)
@ohos.hiSysEvent (系统事件打点)
本模块提供了系统事件打点能力,包括系统事件的埋点、落盘系统事件的订阅及已落盘的系统事件的查询能力。
说明:
- 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
- 本模块的接口为系统接口。
导入模块
import hiSysEvent from '@ohos.hiSysEvent';
EventType
系统事件类型枚举。
系统能力: SystemCapability.HiviewDFX.HiSysEvent
名称 | 值 | 说明 |
---|---|---|
FAULT | 1 | 错误事件类型。 |
STATISTIC | 2 | 统计事件类型。 |
SECURITY | 3 | 安全事件类型。 |
BEHAVIOR | 4 | 用户行为事件类型。 |
SysEventInfo
系统事件信息对象接口。
系统能力: SystemCapability.HiviewDFX.HiSysEvent
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
domain | string | 是 | 事件领域。 |
name | string | 是 | 事件名称。 |
eventType | EventType | 是 | 事件类型。 |
params | object | 否 | 事件参数。 |
hiSysEvent.write
write(info: SysEventInfo, callback: AsyncCallback<void>): void
系统事件打点方法,接收SysEventInfo类型的对象作为事件参数,使用callback方式作为异步回调。
系统能力: SystemCapability.HiviewDFX.HiSysEvent
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
info | SysEventInfo | 是 | 系统事件。 |
callback | AsyncCallback<void> | 是 | 回调函数,可以在回调函数中处理接口返回值。 - 0表示事件校验成功,事件正常异步写入事件文件; - 正值表示事件打点存在异常,但可以正常写入; - 负值表示事件打点失败。 |
错误码:
以下错误码的详细介绍请参见系统事件错误码。
错误码ID | 错误信息 |
---|---|
11200001 | Invalid event domain. |
11200002 | Invalid event name. |
11200003 | Abnormal environment. |
11200004 | Length of the event is over limit. |
11200051 | Invalid event parameter. |
11200052 | Size of the event parameter of the string type is over limit. |
11200053 | Count of event parameters is over limit. |
11200054 | Count of event parameter of the array type is over limit. |
示例:
import hiSysEvent from '@ohos.hiSysEvent';
import { BusinessError } from '@ohos.base';
try {
let customizedParams: Record<string, string|number> = {
'PID': 487,
'UID': 103,
'PACKAGE_NAME': "com.ohos.hisysevent.test",
'PROCESS_NAME': "syseventservice",
'MSG': "no msg."
};
let eventInfo: hiSysEvent.SysEventInfo = {
domain: "RELIABILITY",
name: "STACK",
eventType: hiSysEvent.EventType.FAULT,
params: customizedParams
};
hiSysEvent.write(eventInfo, (err: BusinessError, val: number) => {
// do something here.
});
} catch (err) {
console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`);
}
hiSysEvent.write
write(info: SysEventInfo): Promise<void>
系统事件打点方法,接收SysEventInfo类型的对象作为事件参数,使用promise方式作为异步回调。
系统能力: SystemCapability.HiviewDFX.HiSysEvent
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
info | SysEventInfo | 是 | 系统事件。 |
返回值:
类型 | 说明 |
---|---|
Promise<void> | Promise实例,可以在其then()、catch()方法中分别对系统事件写入成功、写入异常的回调进行处理。 |
错误码:
以下错误码的详细介绍请参见系统事件错误码。
错误码ID | 错误信息 |
---|---|
11200001 | Invalid event domain. |
11200002 | Invalid event name. |
11200003 | Abnormal environment. |
11200004 | Length of the event is over limit. |
11200051 | Invalid event parameter. |
11200052 | Size of the event parameter of the string type is over limit. |
11200053 | Count of event parameters is over limit. |
11200054 | Count of event parameter of the array type is over limit. |
示例:
import hiSysEvent from '@ohos.hiSysEvent';
import { BusinessError } from '@ohos.base';
try {
let customizedParams: Record<string, string|number> = {
'PID': 487,
'UID': 103,
'PACKAGE_NAME': "com.ohos.hisysevent.test",
'PROCESS_NAME': "syseventservice",
'MSG': "no msg."
};
let eventInfo: hiSysEvent.SysEventInfo = {
domain: "RELIABILITY",
name: "STACK",
eventType: hiSysEvent.EventType.FAULT,
params: customizedParams
};
hiSysEvent.write(eventInfo).then(
() => {
// do something here.
}
).catch(
(err: BusinessError) => {
console.error(`error code: ${err.code}, error msg: ${err.message}`);
}
);
} catch (err) {
console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`);
}
RuleType
匹配规则类型枚举。
系统能力: SystemCapability.HiviewDFX.HiSysEvent
名称 | 值 | 说明 |
---|---|---|
WHOLE_WORD | 1 | 全词匹配类型。 |
PREFIX | 2 | 前缀匹配类型。 |
REGULAR | 3 | 正则匹配类型。 |
WatchRule
系统事件订阅规则对象接口。
系统能力: SystemCapability.HiviewDFX.HiSysEvent
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
domain | string | 是 | 事件领域。 |
name | string | 是 | 事件名称。 |
tag | string | 否 | 事件标签。 |
ruleType | RuleType | 是 | 匹配规则类型。 |
Watcher
系统事件订阅者对象接口。
系统能力: SystemCapability.HiviewDFX.HiSysEvent
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
rules | WatchRule[] | 是 | 订阅对象数组,每个订阅者对象包含多个订阅规则。 |
onEvent | function | 是 | 订阅事件的回调方法(info: SysEventInfo) => void。 |
onServiceDied | function | 是 | 系统事件服务关闭的回调方法() => void。 |
hiSysEvent.addWatcher
addWatcher(watcher: Watcher): void
订阅系统事件,接收Watcher类型的对象作为事件参数。
需要权限: ohos.permission.READ_DFX_SYSEVENT
系统能力: SystemCapability.HiviewDFX.HiSysEvent
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
watcher | Watcher | 是 | 系统事件订阅者对象。 |
错误码:
以下错误码的详细介绍请参见系统事件错误码。
错误码ID | 错误信息 |
---|---|
11200101 | Count of watchers is over limit. |
11200102 | Count of watch rules is over limit. |
示例:
import hiSysEvent from '@ohos.hiSysEvent';
import { BusinessError } from '@ohos.base';
let watchRules: hiSysEvent.WatchRule[] = [{
domain: "RELIABILITY",
name: "STACK",
tag: "STABILITY",
ruleType: hiSysEvent.RuleType.WHOLE_WORD,
} as hiSysEvent.WatchRule];
let watcher: hiSysEvent.Watcher = {
rules: watchRules,
onEvent: (info: hiSysEvent.SysEventInfo) => {
// do something here.
},
onServiceDied: () => {
// do something here.
}
};
try {
hiSysEvent.addWatcher(watcher);
} catch (err) {
console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`);
}
hiSysEvent.removeWatcher
removeWatcher(watcher: Watcher): void
取消订阅系统事件,接收Watcher类型的对象作为事件参数。
需要权限: ohos.permission.READ_DFX_SYSEVENT
系统能力: SystemCapability.HiviewDFX.HiSysEvent
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
watcher | Watcher | 是 | 系统事件订阅者对象。 |
错误码:
以下错误码的详细介绍请参见系统事件错误码。
错误码ID | 错误信息 |
---|---|
11200201 | The watcher does not exist. |
示例:
import hiSysEvent from '@ohos.hiSysEvent';
import { BusinessError } from '@ohos.base';
let watchRules: hiSysEvent.WatchRule[] = [{
domain: "RELIABILITY",
name: "STACK",
tag: "STABILITY",
ruleType: hiSysEvent.RuleType.WHOLE_WORD,
} as hiSysEvent.WatchRule ];
let watcher: hiSysEvent.Watcher = {
rules: watchRules,
onEvent: (info: hiSysEvent.SysEventInfo) => {
// do something here.
},
onServiceDied: () => {
// do something here.
}
};
try {
hiSysEvent.addWatcher(watcher);
hiSysEvent.removeWatcher(watcher);
} catch (err) {
console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`);
}
QueryArg
系统事件查询参数对象接口。
系统能力: SystemCapability.HiviewDFX.HiSysEvent
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
beginTime | number | 是 | 查询的系统事件起始时间(13位时间戳)。 |
endTime | number | 是 | 查询的系统事件结束时间(13位时间戳)。 |
maxEvents | number | 是 | 查询的系统事件最多条数。 |
fromSeq10+ | number | 否 | 查询的系统事件起始序列号,默认值为-1。 |
toSeq10+ | number | 否 | 查询的系统事件结束序列号,默认值为-1。 |
QueryRule
系统事件查询规则对象接口。
系统能力: SystemCapability.HiviewDFX.HiSysEvent
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
domain | string | 是 | 查询包含的事件领域。 |
names | string[] | 是 | 查询所包含的多个事件名称,每个查询规则对象包含多个系统事件名称。 |
condition10+ | string | 否 | 事件的额外参数条件,格式:{“version”:“V1”,“condition”:{“and”:[{“param”:“参数”,“op”:“操作符”,“value”:“比较值”}]}} |
Querier
系统事件查询者对象接口。
系统能力: SystemCapability.HiviewDFX.HiSysEvent
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
onQuery | function | 是 | 返回查询到的系统事件的回调方法(infos: SysEventInfo[]) => void。 |
onComplete | function | 是 | 查询结果统计的回调方法(reason: number, total: number) => void。 |
hiSysEvent.query
query(queryArg: QueryArg, rules: QueryRule[], querier: Querier): void
查询系统事件。
需要权限: ohos.permission.READ_DFX_SYSEVENT
系统能力: SystemCapability.HiviewDFX.HiSysEvent
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
queryArg | QueryArg | 是 | 查询需要配置的查询参数。 |
rules | QueryRule[] | 是 | 查询规则数组,每次查询可配置多个查询规则。 |
querier | Querier | 是 | 查询者对象,包含查询结果及结束的相关回调。 |
错误码:
以下错误码的详细介绍请参见系统事件错误码。
错误码ID | 错误信息 |
---|---|
11200301 | Count of query rules is over limit. |
11200302 | Invalid query rule. |
11200303 | Count of concurrent queriers is over limit. |
11200304 | Query frequency is over limit. |
示例:
import hiSysEvent from '@ohos.hiSysEvent';
import { BusinessError } from '@ohos.base';
try {
let customizedParams: Record<string, string|number> = {
'PID': 487,
'UID': 103,
'PACKAGE_NAME': "com.ohos.hisysevent.test",
'PROCESS_NAME': "syseventservice",
'MSG': "no msg."
};
let eventInfo: hiSysEvent.SysEventInfo = {
domain: "RELIABILITY",
name: "STACK",
eventType: hiSysEvent.EventType.FAULT,
params: customizedParams
};
hiSysEvent.write(eventInfo, (err: BusinessError, val: number) => {
// do something here.
});
let queryArg: hiSysEvent.QueryArg = {
beginTime: -1,
endTime: -1,
maxEvents: 5,
};
let queryRules: hiSysEvent.QueryRule[] = [{
domain: "RELIABILITY",
names: ["STACK"],
} as hiSysEvent.QueryRule];
let querier: hiSysEvent.Querier = {
onQuery: (infos: hiSysEvent.SysEventInfo[]) => {
// do something here.
},
onComplete: (reason: number, total: number) => {
// do something here.
}
};
hiSysEvent.query(queryArg, queryRules, querier);
} catch (err) {
console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`);
}
hiSysEvent.exportSysEvents10+
exportSysEvents(queryArg: QueryArg, rules: QueryRule[]): number
批量导出系统事件,以文件格式写入应用沙箱固定目录(/data/storage/el2/base/cache/hiview/event/)。
需要权限: ohos.permission.READ_DFX_SYSEVENT
系统能力: SystemCapability.HiviewDFX.HiSysEvent
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
queryArg | QueryArg | 是 | 导出需要配置的查询参数。 |
rules | QueryRule[] | 是 | 查询规则数组,每次导出可配置多个查询规则。 |
返回值:
类型 | 说明 |
---|---|
number | 接口调用时间戳。 |
错误码:
以下错误码的详细介绍请参见系统事件错误码。
错误码ID | 错误信息 |
---|---|
11200301 | Count of query rules is over limit. |
11200302 | Invalid query rule. |
11200304 | Export frequency is over limit. |
示例:
import hiSysEvent from '@ohos.hiSysEvent';
import fs from '@ohos.file.fs';
import { BusinessError } from '@ohos.base';
try {
let customizedParams: Record<string, string|number> = {
'PID': 487,
'UID': 103,
'PACKAGE_NAME': "com.ohos.hisysevent.test",
'PROCESS_NAME': "syseventservice",
'MSG': "no msg."
};
let eventInfo: hiSysEvent.SysEventInfo = {
domain: "RELIABILITY",
name: "STACK",
eventType: hiSysEvent.EventType.FAULT,
params: customizedParams
};
hiSysEvent.write(eventInfo, (err: BusinessError, val: number) => {
// do something here.
});
let queryArg: hiSysEvent.QueryArg = {
beginTime: -1,
endTime: -1,
maxEvents: 1,
};
let queryRules: hiSysEvent.QueryRule[] = [{
domain: "RELIABILITY",
names: ["STACK"],
} as hiSysEvent.QueryRule];
let time = hiSysEvent.exportSysEvents(queryArg, queryRules);
console.log(`receive export task time is : ${time}`);
// 延迟读取本次导出的事件
setTimeout(() => {
let eventDir = '/data/storage/el2/base/cache/hiview/event';
let filenames = fs.listFileSync(eventDir);
for (let i = 0; i < filenames.length; i++) {
if (filenames[i].indexOf(time.toString()) != -1) {
let res = fs.readTextSync(eventDir + '/' + filenames[i]);
let events: string = JSON.parse('[' + res.slice(0, res.length - 1) + ']');
console.log("read file end, events is :" + JSON.stringify(events));
}
}
}, 10000);
} catch catch (err) {
console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`);
}
hiSysEvent.subscribe10+
subscribe(rules: QueryRule[]): number
订阅实时系统事件(事件需满足低频率或偶发性的约束条件),事件发生时立即以文件格式写入应用沙箱固定目录(/data/storage/el2/base/cache/hiview/event/)。
需要权限: ohos.permission.READ_DFX_SYSEVENT
系统能力: SystemCapability.HiviewDFX.HiSysEvent
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
rules | QueryRule[] | 是 | 查询规则数组,每次订阅可配置多个查询规则。 |
返回值:
类型 | 说明 |
---|---|
number | 接口调用时间戳。 |
错误码:
以下错误码的详细介绍请参见系统事件错误码。
错误码ID | 错误信息 |
---|---|
11200301 | Count of query rules is over limit. |
11200302 | Invalid query rule. |
示例:
import hiSysEvent from '@ohos.hiSysEvent';
import fs from '@ohos.file.fs';
import { BusinessError } from '@ohos.base';
try {
let rules: hiSysEvent.QueryRule[] = [{
domain: "RELIABILITY",
names: ["STACK"],
} as hiSysEvent.QueryRule,
{
domain: "BUNDLE_MANAGER",
names: ["BUNDLE_UNINSTALL"],
} as hiSysEvent.QueryRule];
hiSysEvent.subscribe(rules);
let customizedParams: Record<string, string|number> = {
'PID': 487,
'UID': 103,
'PACKAGE_NAME': "com.ohos.hisysevent.test",
'PROCESS_NAME': "syseventservice",
'MSG': "no msg."
};
let eventInfo: hiSysEvent.SysEventInfo = {
domain: "RELIABILITY",
name: "STACK",
eventType: hiSysEvent.EventType.FAULT,
params: customizedParams
};
hiSysEvent.write(eventInfo, (err: BusinessError, val: number) => {
// do something here.
});
// 延迟读取订阅的事件
setTimeout(() => {
let eventDir = '/data/storage/el2/base/cache/hiview/event';
let filenames = fs.listFileSync(eventDir);
for (let i = 0; i < filenames.length; i++) {
let res = fs.readTextSync(eventDir + '/' + filenames[i]);
let events: string = JSON.parse('[' + res.slice(0, res.length - 1) + ']');
console.log("read file end, events is :" + JSON.stringify(events));
}
}, 10000);
} catch catch (err) {
console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`);
}
hiSysEvent.unsubscribe10+
unsubscribe(): void
取消订阅系统事件。
需要权限: ohos.permission.READ_DFX_SYSEVENT
系统能力: SystemCapability.HiviewDFX.HiSysEvent
错误码:
以下错误码的详细介绍请参见系统事件错误码。
错误码ID | 错误信息 |
---|---|
11200305 | Unsubscribe failed. |
示例:
import hiSysEvent from '@ohos.hiSysEvent';
import { BusinessError } from '@ohos.base';
try {
let rules: hiSysEvent.QueryRule[] = [{
domain: "RELIABILITY",
names: ["STACK"],
} as hiSysEvent.QueryRule,
{
domain: "BUNDLE_MANAGER",
names: ["BUNDLE_UNINSTALL"],
} as hiSysEvent.QueryRule];
hiSysEvent.subscribe(rules);
hiSysEvent.unsubscribe();
} catch (err) {
console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`);
}
你可能感兴趣的鸿蒙文章
harmony 鸿蒙BundleStatusCallback
harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager模块)
harmony 鸿蒙@ohos.distributedBundle (分布式包管理)
harmony 鸿蒙@ohos.bundle (Bundle模块)
harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (企业设备管理扩展能力)
热门推荐
-
2、 - 优质文章
-
3、 gate.io
-
8、 golang
-
9、 openharmony
-
10、 Vue中input框自动聚焦