| RULE_CAUTION_PRINT_LOG | BigInt | Alarm rule, which is programmed to print a log when an alarm is generated.|
| RULE_CAUTION_TRIGGER_CRASH | BigInt | Alarm rule. When an alarm is generated, the application exits.|
| RULE_CAUTION_TRIGGER_CRASH | BigInt | Alarm rule, which is programmed to force the application to exit when an alarm is generated.|
| RULE_THREAD_CHECK_SLOW_PROCESS | BigInt | Caution rule, which is programmed to detect whether any time-consuming function is invoked.|
| RULE_CHECK_SLOW_EVENT | BigInt | Caution rule, which is programmed to detect whether the event distribution or processing time has exceeded the specified time threshold.|
| RULE_CHECK_ABILITY_CONNECTION_LEAK | BigInt | Caution rule, which is programmed to detect whether ability leakage has occurred.|
HiSysEvent supports listening for events across processes. You can register a listener to listen for concerned events on a real-time basis. For example, you can enable the battery module to listen for power consumption event for power usage analysis.
## Available APIs<a name="section0342191810519"></a>
<tdclass="cellrowborder"valign="top"width="51.88%"headers="mcps1.2.3.1.2 "><pid="p14727325133216"><aname="p14727325133216"></a><aname="p14727325133216"></a>Registers a listener for system events. You can listen for certain events by specifying rules.</p>
<aname="ul6717142214919"></a><aname="ul6717142214919"></a><ulid="ul6717142214919"><li><strongid="b5330432115819"><aname="b5330432115819"></a><aname="b5330432115819"></a>listener</strong>: callback object for system events.</li><li><strongid="b1518805912597"><aname="b1518805912597"></a><aname="b1518805912597"></a>rules</strong>: rules for event listening.</li></ul>
<aname="ul12105842111913"></a><aname="ul12105842111913"></a><ulid="ul12105842111913"><li><strongid="b117641849702"><aname="b117641849702"></a><aname="b117641849702"></a>0</strong>: Repeated registration is successful.</li><li><strongid="b2682415314"><aname="b2682415314"></a><aname="b2682415314"></a>1</strong>: Initial registration is successful.</li><li>Other values: Registration has failed.</li></ul>
<tdclass="cellrowborder"valign="top"width="51.88%"headers="mcps1.2.3.1.2 "><pid="p1104194420248"><aname="p1104194420248"></a><aname="p1104194420248"></a>Removes the listener for system events.</p>
<aname="ul894321075411"></a><aname="ul894321075411"></a><ulid="ul894321075411"><li><strongid="b178371510181317"><aname="b178371510181317"></a><aname="b178371510181317"></a>listener</strong>: callback object for system events.</li></ul>
<tdclass="cellrowborder"valign="top"width="51.89%"headers="mcps1.2.3.1.2 "><pid="p94416160565"><aname="p94416160565"></a><aname="p94416160565"></a>Rule type. The matching scope includes <strongid="b638713414175"><aname="b638713414175"></a><aname="b638713414175"></a>domain</strong> and <strongid="b128648618171"><aname="b128648618171"></a><aname="b128648618171"></a>eventName</strong>. The value can be any of the following:</p>
<tdclass="cellrowborder"valign="top"width="51.89%"headers="mcps1.2.3.1.2 "><aname="ul14905926102311"></a><aname="ul14905926102311"></a><ulid="ul14905926102311"><li><strongid="b152431514132110"><aname="b152431514132110"></a><aname="b152431514132110"></a>domain</strong>: domain to which the event belongs. By default, an empty string indicates that the domain is successfully matched.</li></ul>
<tdclass="cellrowborder"valign="top"width="51.89%"headers="mcps1.2.3.1.2 "><aname="ul248063132319"></a><aname="ul248063132319"></a><ulid="ul248063132319"><li><strongid="b197622401229"><aname="b197622401229"></a><aname="b197622401229"></a>eventName</strong>: event name. By default, an empty string indicates that the event name is successfully matched.</li></ul>
<tdclass="cellrowborder"valign="top"width="51.74999999999999%"headers="mcps1.2.3.1.2 "><pid="p1772213111011"><aname="p1772213111011"></a><aname="p1772213111011"></a>Callback object for system events.</p>
HiSysEvent supports listening for events across processes. You can register a listener to listen for concerned events on a real-time basis. For example, you can enable the battery module to listen for power consumption events for power usage analysis.
Before subscribing to system events, you need to configure HiSysEvent logging. For details, see [HiSysEvent Logging Configuration](subsys-dfx-hisysevent-logging-config.md).
## Development Guidelines<a name="section315316685113"></a>
### Available APIs<a name="section0342191810519"></a>
**Table 1** EventListener APIs
| API| Description|
| -------- | --------- |
|bool HiSysEventManager::AddEventListener(std::shared_ptr<HiSysEventSubscribeCallBackBase> listener, std::vector<ListenerRule>& rules)|Registers a listener for system events. You can listen for certain events by specifying rules. <br><br>Input arguments: <ul><li>**listener**: callback object for system events. </li><li>**rules**: rules for event listening. </li></ul>Return value:<ul><li>**0**: Repeated registration is successful. </li><li>**1**: Initial registration is successful. </li><li>Other values: Registration has failed.</li></ul>|
|bool HiSysEventManager::RemoveListener(std::shared_ptr<HiSysEventSubscribeCallBackBase> listener)|Removes the listener for system events. <br><br>Input argument: <ul><li>**listener**: callback object for system events. </ul>Return value:<br>  None.|
**Table 2** Description of ListenerRule
| API| Description|
| -------- | --------- |
|ListenerRule(const std::string& tag, RuleType ruleType = RuleType::WHOLE_WORD)|Constructor used to create a **ListenerRule** object based on the event tag. <br><br>Input arguments:<ul><li>**tag**: indicates the event tag for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, lowercase letters, and digits. </li><li>**ruleType**: indicates the type of the **ListenerRule** object. The value is an enum defined by **RuleType**.</li></ul>|
|ListenerRule(const std::string& domain, const std::string& eventName, RuleType ruleType = RuleType::WHOLE_WORD)|Constructor used to create a **ListenerRule** object based on the event domain and event name. <br><br>Input arguments: <ul><li>**domain**: indicates the event domain for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, digits, and underscores (_). </li><li>**eventName**: indicates the event name for the **ListenerRule** object. The value is a string of 1 to 32 characters, including uppercase letters, digits, and underscores (_). </li><li>**ruleType**: indicates the type of the **ListenerRule** object. The value is an enum defined by **RuleType**.</li></ul>|
|ListenerRule(const std::string& domain, const std::string& eventName, const std::string& tag, RuleType ruleType = RuleType::WHOLE_WORD)|Constructor used to create a **ListenerRule** object based on the event domain, event name, and event tag. <br><br>Input arguments:<ul><li>**tag**: indicates the event tag for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, lowercase letters, and digits. </li><li>**domain**: indicates the event domain for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, digits, and underscores (_). </li><li>**eventName**: indicates the event name for the **ListenerRule** object. The value is a string of 1 to 32 characters, including uppercase letters, digits, and underscores (_). </li><li>**ruleType**: indicates the type of the **ListenerRule** object. The value is an enum defined by **RuleType**.</li></ul>|
**Table 3** Description of RuleType
| Enum| Description|
| ------------ | ------------- |
| WHOLE_WORD | Whole word matching|
| PREFIX | Prefix matching|
| REGULAR | Regular expression matching|
**Table 4** Description of HiSysEventSubscribeCallBackBase
| API| Description|
| -------- | --------- |
|void HiSysEventSubscribeCallBackBase::OnHandle(const std::string& domain, const std::string& eventName, const int eventType, const std::string& eventDetail)|Provides the callback of system events. <br><br>Input arguments: <ul><li>**domain**: indicates the domain to which the event belongs. </li><li>**eventName**: indicates the event name. </li><li>**eventType**: indicates the event type. </li><li>**eventDetail**: indicates the event information, in JSON format. </li></ul>Return value:<br>  None.|
### Development Example<a name="section123181432175110"></a>
C++
1. Develop the source code.
- Import the corresponding header file:
Import the **DemoListener.h** header file, which contains the **DemoListener** class for implementing the custom event callback.
-[Verifying the YAML File](#section123181432175115)
-[Configuring the YAML File Path](#section123181432175135)
-[Compiling the YAML File](#section123181432175137)
-[Logging and Querying Events](#section123181432175139)
## Overview<a name="section315316685115"></a>
If HiSysEvent logging is required for a component, you need to define a YAML file and [configure the YAML file path](#section123181432175135) in the **bundle.js** file. During compilation, the OpenHarmony compilation framework will use the Python compilation script to parse and verify all the YAML files configured in the **bundle.js** file. On completion, the compilation framework will summarize the configuration information in the YAML files and convert the information into a JSON file named **hisysevent.def**. After that, the compilation framework will put the JSON file to a specified path as the basis for the system to determine whether to log system events.
Understanding the following concepts would be helpful for you in configuring HiSysEvent logging.
- Event domain
Represents the domain to which an event belongs. It is specified by the **domain** field in the YAML file. For details, see [domain](#section123181432175123) in the example YAML file.
- Event name
Indicates the events in an event domain. For details, see [EVENT\_NAMEA/EVENT\_NAMEB](#section123181432175123) in the example YAML file.
- Parameter
Defines the key values in an event name. For details, see [__BASE/NAME1/NAME2](#section123181432175123) in the example YAML file.
- Each YAML file can contain only one event domain, and the domain name cannot be the same as that defined in other YAML files.
- Zero or more event names can be defined for one event domain. The event names in the same event domain must be unique.
- Multiple parameters can be defined for one event name. The parameters in the same event name must be unique. There must be one and only one parameter named **\__BASE** in each event name. See Table 1 for the fields of this parameter and Table 2 for the fields of other custom parameters.
**Table 1** Fields in the \__BASE parameter
| Field| Description|
| ----- | ----- |
| type | Indicates the type of the event. This field is mandatory. <br><br>Value:<ul><li>**FAULT**: fault </li><li>**STATISTIC**: statistics </li><li>**SECURITY**: security </li><li>**BEHAVIOR**: user behavior</li></ul> |
| level | Indicates the level of the event. This field is mandatory. <br><br>Value: <ul><li>**CRITICAL**: critical </li><li>**MINOR**: minor</li></ul> |
| tag | Indicates the tag of the event. This field is mandatory. <br><br>Rule:<ul><li>You can define a maximum of five tags,separated with a space. </li><li>A single tag can contain a maximum of 16 characters, including a to z, A to Z, and 0 to 9.</li></ul>|
| desc | Describes the event name. This field is mandatory. <br><br>Rule:<ul><li>The description contains 3 to 128 characters, including a to z, A to Z, 0 to 9, and underscores (_).</li></ul>|
**Table 2** Description of custom parameters
| Field| Description|
| ----- | ----- |
| type | Indicates the type of a parameter. This field is mandatory. <br><br>Value: <ul><li>BOOL</li><li>UINT8</li><li>UINT16</li><li>INT32</li><li>UINT32</li><li>UINT64</li><li>FLOAT</li><li>DOUBLE</li><li>STRING</li></ul>|
| arrsize | Specifies the length of the parameter of the array type. This field is optional. <br><br>Value range: <ul><li>1-100</li></ul>|
| desc | Describes the parameter. This field is mandatory. <br><br>Rule:<ul><li>The description contains 3 to 128 characters, including a to z, A to Z, 0 to 9, and underscores (_).</li></ul>|
## Writing a YAML File<a name="section123181432175113"></a>
- The name must start with a letter and can contain only uppercase letters, digits, and underscores (_).
- The name contains 1 to 16 characters.
- Event naming rules:
- The name must start with a letter and can contain only uppercase letters, digits, and underscores (_).
- The name contains 1 to 32 characters.
- The number of internal event names in an event domain cannot exceed 4096.
- Parameter naming rules:
- The name must start with a letter and can contain only uppercase letters, digits, and underscores (_).
- The name contains 1 to 32 characters.
- The number of parameters in an event domain cannot exceed 128.
### Example<a name="section123181432175123"></a>
- In the example YAML file, the event domain name is **MODULEA**. The event domain contains two events named **EVENT\_NAMEA** and **EVENT\_NAMEB**.
-**EVENT\_NAMEA** is defined as a critical event of the fault type. The event contains the **NAME1** parameter of the string type, the **NAME2** parameter of the string type, and the **NAME3** parameter of the unsigned short integer type. Therefore, you can perform [real-time subscription](subsys-dfx-hisysevent-listening.md) to the event based on the event domain **MODULEA** and event name **EVENT\_NAMEA**.
-**EVENT\_NAMEB** is defined as a general event of the statistics type. The event contains the **NAME1** parameter of the unsigned short integer type and the **NAME2** parameter of the integer type. Because two event tags named **tag1** and **tag2** are defined for **EVENT\_NAMEB** in the **\__BASE** parameter, you can perform [real-time subscription](subsys-dfx-hisysevent-read.md) to the event based on the event domain **MODULEA** and event name **EVENT\_NAMEB**, or based on the event tag.
```
##########################################
# HiSysEvent definition for MODULEA
##########################################
domain: MODULEA
EVENT_NAMEA:
__BASE: {type: FAULT, level: CRITICAL, desc: event name a}
>The YAML file can be placed in any directory of the component project as needed. You only need to specify the path in the **bundle.js** file.
### Compiling the YAML File<a name="section123181432175137"></a>
- Perform full compilation.
- During full compilation of the system, the configuration in the YAML files of all components are summarized. After the compilation is complete, the **hisysevent.def** file will be generated in the specified directory.
```
cd absolute path of the project's root directory
./build --product-name <product name>
```
- To obtain the **hisysevent.def** file generated after full compilation, run the following command:
```
cd absolute path of the project's root directory
find out -name hisysevent.def -type f
```
- Single-file compilation:
You can also compile the YAML file of a single component by running the following commands:
```
cd absolute path of the project's root directory
./build/ohos/hisysevent/gen_def_from_all_yaml.py --yaml-list <yaml file list> --def-path <file store directory>
```
**Table 3** Parameters for single-file compilation
| Parameter| Description|
| ------ | ------ |
| --yaml-list | Specifies the paths of the YAML files to be compiled. If there are multiple YAML file paths, separate each of them with a space.|
| --def-path | Specifies the path of the **hisysevent.def** file generated after compilation.|
### Logging and Querying Events<a name="section123181432175139"></a>
1. Push the **hisysevent.def** file to the **/system/etc/hiview/** directory of the device by using the [hdc_std tool](subsys-toolchain-hdc-guide.md).
2. Trigger logging of the custom system events in the YAML file. Then, run [hisysevent -l](subsys-dfx-hisysevent-tool.md) to query historical system events to find out if the logging of the custom system events is successful.
HiSysEvent provides an API for you to query system events. You can query concerned events by specifying search criteria. For example, for a power consumption module, you can query required system events for analysis.
## Development Guidelines<a name="section315316761113"></a>
### Available APIs<a name="section03869128521"></a>
**Table 1** HiSysEvent query API
| API| Description|
| -------- | --------- |
| bool HiSysEventManager::QueryHiSysEvent(struct QueryArg& queryArg, std::vector<struct QueryRule>& queryRules, std::shared_ptr<HiSysEventQueryCallBackBase> queryCallBack) | Queries system events by specifying search criteria such as the time segment, event domain, and event name. <br><br>Input arguments:<ul><li>**queryArg**: event query parameter. </li><li>**queryRules**: event filtering rules. </li><li>**queryRules**: callback object for query results. </li></ul>Return value:<ul><li>**true**: The query is successful. </li><li>**false**: The query has failed.</li></ul> |
**Table 2** Description of QueryArg
| Attribute| Description|
| -------- | --------- |
| beginTime | Start time, in the **long long int** format.|
| endTime | End time, in the **long long int** format.|
| maxEvents | Maximum number of returned events, in the **int** format.|
**Table 3** Description of QueryRule
| Attribute| Description|
| -------- | --------- |
| ruleType | Rule type, in the **uint32_t** format. The default value is **0**.|
| domain | Domain to which the event belongs, in the **string** format. By default, an empty string indicates that the domain is successfully matched.|
| eventList | Event name list, in the std::vector<std::string> format. By default, an empty string indicates that the event names on the list are successfully matched.|
**Table 4** Description of HiSysEventQueryCallBackBase
| void HiSysEventQueryCallBackBase::OnComplete(int32_t reason, int32_t total) | Callback object for completion of event query. <br><br>Input arguments:<ul><li>**reason**: reason for completion of event query. The default value is **0**. </li><li>**total**: total number of events returned in this query. </li></ul>Return value:<br>  None.|
### Development Example<a name="section14286111855212"></a>
HiSysEvent provides an API for you to query system events. You can query concerned events by specifying search criteria. For example, for a power consumption module, you can query required system events for analysis.
## Available APIs<a name="section03869128521"></a>
<tdclass="cellrowborder"valign="top"width="51.88%"headers="mcps1.2.3.1.2 "><pid="p14727325133216"><aname="p14727325133216"></a><aname="p14727325133216"></a>Queries system events by specifying search criteria such as the time segment, event domain, and event name.</p>
<tbody><trid="row3784451122012"><tdclass="cellrowborder"valign="top"width="47.85%"headers="mcps1.2.3.1.1 "><pid="p2078414512209"><aname="p2078414512209"></a><aname="p2078414512209"></a>long long beginTime</p>
<trid="row1564913158230"><tdclass="cellrowborder"valign="top"width="47.85%"headers="mcps1.2.3.1.1 "><pid="p11649191511239"><aname="p11649191511239"></a><aname="p11649191511239"></a>long long endTime</p>
<tdclass="cellrowborder"valign="top"width="52.15%"headers="mcps1.2.3.1.2 "><pid="p1161901214232"><aname="p1161901214232"></a><aname="p1161901214232"></a>Maximum number of query records.</p>
<tdclass="cellrowborder"valign="top"width="51.970000000000006%"headers="mcps1.2.3.1.2 "><pid="p94416160565"><aname="p94416160565"></a><aname="p94416160565"></a>Rule type. The default value is <strongid="b196007205817"><aname="b196007205817"></a><aname="b196007205817"></a>0</strong>.</p>
<tdclass="cellrowborder"valign="top"width="51.970000000000006%"headers="mcps1.2.3.1.2 "><aname="ul14905926102311"></a><aname="ul14905926102311"></a><ulid="ul14905926102311"><li><strongid="b9813231789"><aname="b9813231789"></a><aname="b9813231789"></a>domain</strong>: domain to which the event belongs. By default, an empty string indicates that the domain is successfully matched.</li></ul>
<tdclass="cellrowborder"valign="top"width="51.970000000000006%"headers="mcps1.2.3.1.2 "><aname="ul248063132319"></a><aname="ul248063132319"></a><ulid="ul248063132319"><li><strongid="b172129351784"><aname="b172129351784"></a><aname="b172129351784"></a>eventList</strong>: event name list. By default, an empty string indicates that the event names on the list are successfully matched.</li></ul>
<tdclass="cellrowborder"valign="top"width="51.970000000000006%"headers="mcps1.2.3.1.2 "><pid="p126315352130"><aname="p126315352130"></a><aname="p126315352130"></a>Callback object for completion of event query.</p>
<aname="ul106383518130"></a><aname="ul106383518130"></a><ulid="ul106383518130"><li><strongid="b855743017177"><aname="b855743017177"></a><aname="b855743017177"></a>reason</strong>: reason for completion of event query. The default value is <strongid="b5175337111718"><aname="b5175337111718"></a><aname="b5175337111718"></a>0</strong>.</li><li><strongid="b1196583151911"><aname="b1196583151911"></a><aname="b1196583151911"></a>total</strong>: total number of events returned in this query.</li></ul>
