harmony 鸿蒙@ohos.hiSysEvent (系统事件打点)

  • 2022-08-09
  • 浏览 (1039)

@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&lt;void&gt;

系统事件打点方法,接收SysEventInfo类型的对象作为事件参数,使用promise方式作为异步回调。

系统能力: SystemCapability.HiviewDFX.HiSysEvent

参数:

参数名 类型 必填 说明
info SysEventInfo 系统事件。

返回值:

类型 说明
Promise&lt;void&gt; 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 鸿蒙接口

harmony 鸿蒙系统公共事件定义(待停用)

harmony 鸿蒙系统公共事件定义

harmony 鸿蒙开发说明

harmony 鸿蒙企业设备管理概述(仅对系统应用开放)

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager模块)

harmony 鸿蒙@ohos.distributedBundle (分布式包管理)

harmony 鸿蒙@ohos.bundle (Bundle模块)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (企业设备管理扩展能力)

0  赞