@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';

try {
    hiSysEvent.write({
        domain: "RELIABILITY",
        name: "STACK",
        eventType: hiSysEvent.EventType.FAULT,
        params: {
            PID: 487,
            UID: 103,
            PACKAGE_NAME: "com.ohos.hisysevent.test",
            PROCESS_NAME: "syseventservice",
            MSG: "no msg."
        }
    }, (err, val) => {
        // do something here.
    })
} catch (error) {
    console.error(`error code: ${error.code}, error msg: ${error.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';

try {
    hiSysEvent.write({
        domain: "RELIABILITY",
        name: "STACK",
        eventType: hiSysEvent.EventType.FAULT,
        params: {
            PID: 487,
            UID: 103,
            PACKAGE_NAME: "com.ohos.hisysevent.test",
            PROCESS_NAME: "syseventservice",
            MSG: "no msg."
        }
    }).then(
        (val) => {
            // do something here.
        }
    ).catch(
        (err) => {
            // do something here.
        }
    )
} catch (error) {
    console.error(`error code: ${error.code}, error msg: ${error.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';

let watcher = {
    rules: [{
        domain: "RELIABILITY",
        name: "STACK",
        tag: "STABILITY",
        ruleType: hiSysEvent.RuleType.WHOLE_WORD,
    }],
    onEvent: (info) => {
        // do something here.
    },
    onServiceDied: () => {
        // do something here.
    }
}
try {
    hiSysEvent.addWatcher(watcher)
} catch (error) {
    console.error(`error code: ${error.code}, error msg: ${error.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';

let watcher = {
    rules: [{
        domain: "RELIABILITY",
        name: "STACK",
        tag: "STABILITY",
        ruleType: hiSysEvent.RuleType.WHOLE_WORD,
    }],
    onEvent: (info) => {
        // do something here.
    },
    onServiceDied: () => {
        // do something here.
    }
}
try {
    hiSysEvent.addWatcher(watcher)
    hiSysEvent.removeWatcher(watcher)
} catch (error) {
    console.error(`error code: ${error.code}, error msg: ${error.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.

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.

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';

try {
    hiSysEvent.write({
        domain: "RELIABILITY",
        name: "STACK",
        eventType: hiSysEvent.EventType.FAULT,
        params: {
            PID: 487,
            UID: 103,
            PACKAGE_NAME: "com.ohos.hisysevent.test",
            PROCESS_NAME: "syseventservice",
            MSG: "no msg."
        }
    }, (err, val) => {
        // do something here.
    })
    hiSysEvent.query({
        beginTime: -1,
        endTime: -1,
        maxEvents: 5,
    }, [{
        domain: "RELIABILITY",
        names: ["STACK"],
    }], {
        onQuery: function (infos) {
            // do something here.
        },
        onComplete: function(reason, total) {
            // do something here.
        }
    })
} catch (error) {
    console.error(`error code: ${error.code}, error msg: ${error.message}`);
}