@ohos.hiSysEvent (System Event Logging)

The hiSysEvent module provides the system event logging functions, such as configuring trace points, subscribing to system events, and querying system events written to the event file.

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

The APIs provided by this module are system APIs.

Modules to Import

import hiSysEvent from '@ohos.hiSysEvent';

EventType

Enumerates event types.

System capability: SystemCapability.HiviewDFX.HiSysEvent

Name	Value	Description
FAULT	1	Error event.
STATISTIC	2	Statistic event.
SECURITY	3	Security event.
BEHAVIOR	4	User behavior event.

SysEventInfo

Defines a system event.

System capability: SystemCapability.HiviewDFX.HiSysEvent

Name	Type	Mandatory	Description
domain	string	Yes	Event domain.
name	string	Yes	Event name.
eventType	EventType	Yes	Event type.
params	object	No	Event parameters.

hiSysEvent.write

write(info: SysEventInfo, callback: AsyncCallback<void>): void

Writes event information to the event file. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.HiviewDFX.HiSysEvent

Parameters

Name	Type	Mandatory	Description
info	SysEventInfo	Yes	System event information.
callback	AsyncCallback<void>	Yes	Callback used to process the received return value. - Value 0: The event verification is successful, and the event will be written to the event file asynchronously. - A value greater than 0: Invalid parameters are present in the event, and the event will be written to the event file asynchronously after the invalid parameters are ignored. - A value smaller than 0: The event parameter verification fails, and the event will not be written to the event file.

Error codes

For details about the error codes, see HiSysEvent Error Codes.

ID	Error Message
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.

Example

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>

Writes event information to the event file. This API uses a promise to return the result.

System capability: SystemCapability.HiviewDFX.HiSysEvent

Parameters

Name	Type	Mandatory	Description
info	SysEventInfo	Yes	System event information.

Return value

Type	Description
Promise<void>	Promise used to return the result. Depending on whether event writing is successful, you can use the then() or catch() method to process the callback.

Error codes

For details about the error codes, see HiSysEvent Error Codes.

ID	Error Message
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.

Example

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

Enumerates matching rule types.

System capability: SystemCapability.HiviewDFX.HiSysEvent

Name	Value	Description
WHOLE_WORD	1	Whole word matching.
PREFIX	2	Prefix matching.
REGULAR	3	Regular expression matching.

WatchRule

Defines event subscription rules.

System capability: SystemCapability.HiviewDFX.HiSysEvent

Name	Type	Mandatory	Description
domain	string	Yes	Event domain.
name	string	Yes	Event name.
tag	string	No	Event tag.
ruleType	RuleType	Yes	Matching rule type.

Watcher

Defines a watcher for event subscription.

System capability: SystemCapability.HiviewDFX.HiSysEvent

Name	Type	Mandatory	Description
rules	WatchRule[]	Yes	Array of matching event subscription rules.
onEvent	function	Yes	Callback for event subscription: (info: SysEventInfo) => void
onServiceDied	function	Yes	Callback for disabling of event subscription: () => void

hiSysEvent.addWatcher

addWatcher(watcher: Watcher): void

Adds a watcher for event subscription.

Required permission: ohos.permission.READ_DFX_SYSEVENT

System capability: SystemCapability.HiviewDFX.HiSysEvent

Parameters

Name	Type	Mandatory	Description
watcher	Watcher	Yes	Watcher for event subscription.

Error codes

For details about the error codes, see HiSysEvent Error Codes.

ID	Error Message
11200101	Count of watchers is over limit.
11200102	Count of watch rules is over limit.

Example

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

Removes a watcher used for event subscription.

Required permission: ohos.permission.READ_DFX_SYSEVENT

System capability: SystemCapability.HiviewDFX.HiSysEvent

Parameters

Name	Type	Mandatory	Description
watcher	Watcher	Yes	Watcher for event subscription.

Error codes

For details about the error codes, see HiSysEvent Error Codes.

ID	Error Message
11200201	The watcher does not exist.

Example

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

Defines arguments for an event query.

System capability: SystemCapability.HiviewDFX.HiSysEvent

Name	Type	Mandatory	Description
beginTime	number	Yes	Start time (13-digit timestamp) for the event query.
endTime	number	Yes	End time (13-digit timestamp) for the event query.
maxEvents	number	Yes	Maximum number of events that can be queried.
fromSeq¹⁰⁺	number	No	Start SN of the events to be queried. The default value is -1.
toSeq¹⁰⁺	number	No	End SN of the system events to be queried. The default value is -1.

QueryRule

Defines event query rules.

System capability: SystemCapability.HiviewDFX.HiSysEvent

Name	Type	Mandatory	Description
domain	string	Yes	Event domain.
names	string[]	Yes	Array of event names. A QueryRule object contains multiple system event names.
condition¹⁰⁺	string	No	Additional event conditions. The value of this parameter is in the format of {"version":"V1","condition":{"and":[{"param":"Parameter","op":"Operator","value":"Comparison value"}]}}.

Querier

Defines an event query instance.

System capability: SystemCapability.HiviewDFX.HiSysEvent

Name	Type	Mandatory	Description
onQuery	function	Yes	Callback used to return the queried system events: (infos: SysEventInfo[]) => void.
onComplete	function	Yes	Callback used to return the query result statistics: (reason: number, total: number) => void

hiSysEvent.query

query(queryArg: QueryArg, rules: QueryRule[], querier: Querier): void

Queries system events.

Required permission: ohos.permission.READ_DFX_SYSEVENT

System capability: SystemCapability.HiviewDFX.HiSysEvent

Parameters

Name	Type	Mandatory	Description
queryArg	QueryArg	Yes	Arguments for event query.
rules	QueryRule[]	Yes	Array of event query rules.
querier	Querier	Yes	Event query instance.

Error codes

For details about the error codes, see HiSysEvent Error Codes.

ID	Error Message
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.

Example

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.exportSysEvents¹⁰⁺

exportSysEvents(queryArg: QueryArg, rules: QueryRule[]): number

Exports system events in batches and writes them as a file to the fixed directory of the application sandbox (that is, /data/storage/el2/base/cache/hiview/event/).

Required permission: ohos.permission.READ_DFX_SYSEVENT

System capability: SystemCapability.HiviewDFX.HiSysEvent

Parameters

Name	Type	Mandatory	Description
queryArg	QueryArg	Yes	Event query parameters for the export.
rules	QueryRule[]	Yes	Array of event query rules for the export.

Return value

Type	Description
number	API call timestamp.

Error codes

For details about the error codes, see HiSysEvent Error Codes.

ID	Error Message
11200301	Count of query rules is over limit.
11200302	Invalid query rule.
11200304	Export frequency is over limit.

Example

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}`);

  // Postpone reading of exported events.
  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.subscribe¹⁰⁺

subscribe(rules: QueryRule[]): number

Subscribes to real-time system events that occur occasionally or occur in a low frequency. These events are written as a file to the fixed directory of the application sandbox (that is, /data/storage/el2/base/cache/hiview/event/).

Required permission: ohos.permission.READ_DFX_SYSEVENT

System capability: SystemCapability.HiviewDFX.HiSysEvent

Parameters

Name	Type	Mandatory	Description
rules	QueryRule[]	Yes	Array of event query rules for the subscription.

Return value

Type	Description
number	API call timestamp.

Error codes

For details about the error codes, see HiSysEvent Error Codes.

ID	Error Message
11200301	Count of query rules is over limit.
11200302	Invalid query rule.

Example

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.
  });

  // Postpone reading of subscribed events.
  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.unsubscribe¹⁰⁺

unsubscribe(): void

Unsubscribes from system events.

Required permission: ohos.permission.READ_DFX_SYSEVENT

System capability: SystemCapability.HiviewDFX.HiSysEvent

Error codes

For details about the error codes, see HiSysEvent Error Codes.

ID	Error Message
11200305	Unsubscribe failed.

Example

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 鸿蒙APIs

harmony 鸿蒙System Common Events (To Be Deprecated Soon)

harmony 鸿蒙System Common Events

harmony 鸿蒙API Reference Document Description

harmony 鸿蒙Enterprise Device Management Overview (for System Applications Only)

harmony 鸿蒙BundleStatusCallback

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

harmony 鸿蒙@ohos.distributedBundle (Distributed Bundle Management)

harmony 鸿蒙@ohos.bundle (Bundle)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)

harmony 鸿蒙@ohos.hiSysEvent (System Event Logging)

@ohos.hiSysEvent (System Event Logging)

Modules to Import

EventType

SysEventInfo

hiSysEvent.write

hiSysEvent.write

RuleType

WatchRule

Watcher

hiSysEvent.addWatcher

hiSysEvent.removeWatcher

QueryArg

QueryRule

Querier

hiSysEvent.query

hiSysEvent.exportSysEvents¹⁰⁺

hiSysEvent.subscribe¹⁰⁺

hiSysEvent.unsubscribe¹⁰⁺

你可能感兴趣的鸿蒙文章

标签云

最热博客

最新博客

@ohos.hiSysEvent (System Event Logging)

Modules to Import

EventType

SysEventInfo

hiSysEvent.write

hiSysEvent.write

RuleType

WatchRule

Watcher

hiSysEvent.addWatcher

hiSysEvent.removeWatcher

QueryArg

QueryRule

Querier

hiSysEvent.query

hiSysEvent.exportSysEvents10+

hiSysEvent.subscribe10+

hiSysEvent.unsubscribe10+

你可能感兴趣的鸿蒙文章

标签云

最热博客

最新博客

hiSysEvent.exportSysEvents¹⁰⁺

hiSysEvent.subscribe¹⁰⁺

hiSysEvent.unsubscribe¹⁰⁺