1# HiSysEvent Listening 2 3 4## Overview 5 6 7### Introduction 8 9HiSysEvent 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. 10 11 12### Constraints 13 14Before subscribing to system events, you need to configure HiSysEvent logging. For details, see [HiSysEvent Logging Configuration](../subsystems/subsys-dfx-hisysevent-logging-config.md). 15 16 17## Development Guidelines 18 19 20### Available APIs 21 22 **Table 1** Description of HiSysEventListener APIs 23 24| API| Description| 25| -------- | -------- | 26| int32_t HiSysEventManager::AddListener(std::shared_ptr<HiSysEventListener> listener, std::vector<ListenerRule>& rules) | Registers a listener for system events. You can listen for certain events by specifying rules.<br>Input arguments:<br>- **listener**: callback object for system events.<br>- **rules**: rules for event listening.<br>Return value:<br>- **0**: Registration is successful.<br>- A negative value: Registration has failed.| 27| int32_t HiSysEventManager::RemoveListener(std::shared_ptr<HiSysEventListener> listener) | Removes the listener for system events.<br>Input arguments:<br>- **listener**: callback object for system events.<br>Return value:<br>- **0**: Canceling registration is successful.<br>- A negative value: Canceling registration has failed. | 28 29 **Table 2** Description of ListenerRule 30 31| API| Description| 32| -------- | -------- | 33| ListenerRule(const std::string& tag, RuleType ruleType = RuleType::WHOLE_WORD) | Constructor used to create a **ListenerRule** object based on the event tag.<br>Input arguments:<br>- **tag**: event tag for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, lowercase letters, and digits.<br>- **ruleType**: type of the **ListenerRule** object. The value is an enum defined by **RuleType**.| 34| 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>Input arguments:<br>- **domain**: event domain for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, digits, and underscores.<br>- **eventName**: event name for the **ListenerRule** object. The value is a string of 1 to 32 characters, including uppercase letters, digits, and underscores.<br>- **ruleType**: type of the **ListenerRule** object. The value is an enum defined by **RuleType**.| 35| 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>Input arguments:<br>- **tag**: event tag for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, lowercase letters, and digits.<br>- **domain**: event domain for the **ListenerRule** object. The value is a string of 1 to 16 characters, including uppercase letters, digits, and underscores.<br>- **eventName**: event name for the **ListenerRule** object. The value is a string of 1 to 32 characters, including uppercase letters, digits, and underscores.<br>- **ruleType**: type of the **ListenerRule** object. The value is an enum defined by **RuleType**.| 36 37 **Table 3** Description of RuleType 38 39| Value| Description| 40| -------- | -------- | 41| WHOLE_WORD | Whole word matching| 42| PREFIX | Prefix matching| 43| REGULAR | Regular expression matching| 44 45 **Table 4** Description of HiSysEventListener 46 47| API| Description| 48| -------- | -------- | 49| void HiSysEventListener::OnEvent(std::shared_ptr<HiSysEventRecord> sysEvent) | Callback object for system events.<br>Input arguments:<br>- **sysEvent**: real-time system events.<br>Return value:<br>None.| 50| void HiSysEventListener::OnServiceDied() | Callback object for service exceptions.<br>Input arguments:<br>None.<br>Return value:<br>None.| 51 52**Table 5** Description of HiSysEventRecord 53| API| Description| 54| -------- | -------- | 55|std::string HiSysEventRecord::AsJson()|Obtains the content of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Content of the system event.| 56|std::string HiSysEventRecord::GetDomain()|Obtains the domain name of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Domain name of the system event.| 57|std::string HiSysEventRecord::GetEventName()|Obtains the name of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Name of the system event.| 58|HiSysEvent::EventType HiSysEventRecord::GetEventType()|Obtains the type of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Type of the system event.| 59|std::string HiSysEventRecord::GetLevel()|Obtains the level of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Level of the system event.| 60|std::string HiSysEventRecord::GetTag()|Obtains the tag of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Tag of the system event.| 61|std::string HiSysEventRecord::GetTimeZone()|Obtains the time zone of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Time zone, in the format of **+0800**.| 62|int HiSysEventRecord::GetTraceFlag()|Obtains the distributed call chain tracing flag of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Distributed call chain tracing flag.| 63|int64_t HiSysEventRecord::GetPid()|Obtains the ID of the process that flushes a system event to the disk.<br>Input arguments:<br>None.<br>Return value:<br>Process ID.| 64|int64_t HiSysEventRecord::GetTid()|Obtains the thread ID of the process that flushes a system event to the disk.<br>Input arguments:<br>None.<br>Return value:<br>Thread ID.| 65|int64_t HiSysEventRecord::GetUid()|Obtains the user ID of the process that flushes a system event to the disk.<br>Input arguments:<br>None.<br>Return value:<br>User ID.| 66|uint64_t HiSysEventRecord::GetPspanId()|Obtains the parent span ID of the distributed call chain tracing task.<br>Input arguments:<br>None.<br>Return value:<br>Parent span ID of the distributed call chain tracing task.| 67|uint64_t HiSysEventRecord::GetSpandId()|Obtains the span ID of the distributed call chain tracing task.<br>Input arguments:<br>None.<br>Return value:<br>Span ID of the distributed call chain tracing task.| 68|uint64_t HiSysEventRecord::GetTime()|Obtains the timestamp of a system event.<br>Input arguments:<br>None.<br>Return value:<br>Timestamp of the system event.| 69|uint64_t HiSysEventRecord::GetTraceId()|Obtains the ID of the distributed call chain tracing task.<br>Input arguments:<br>None.<br>Return value:<br>ID of the distributed call chain tracing task.| 70|void HiSysEventRecord::GetParamNames(std::vector<std::string>& params)|Obtains all key names of a system event.<br>Input arguments:<br>- **params**: key name array reference.<br>Return value:<br>None.| 71|int HiSysEventRecord::GetParamValue(const std::string& param, int64_t& value)|Parses the value of the **param** key in a system event into an int64\_t value.<br>Input arguments:<br>- **param**: key name.<br>- **value**: int64\_t reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.| 72|int HiSysEventRecord::GetParamValue(const std::string& param, uint64_t& value)|Parses the value of the **param** key in a system event into a uint64\_t value.<br>Input arguments:<br>- **param**: key name.<br>- **value**: uint64\_t reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.| 73|int HiSysEventRecord::GetParamValue(const std::string& param, double& value)|Parses the value of the **param** key in a system event into a double value.<br>Input arguments:<br>- **param**: key name.<br>- **value**: double reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.| 74|int HiSysEventRecord::GetParamValue(const std::string& param, std::string& value)|Parses the value of the **param** key in a system event into a string value.<br>Input arguments:<br>- **param**: key name.<br>- **value**: std::string reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.| 75|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<int64_t>& value)|Parses the value of the **param** key in a system event into an int64\_t array.<br>Input arguments:<br>- **param**: key name.<br>- **value**: int64\_t array reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.| 76|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<uint64_t>& value)|Parses the value of the **param** key in a system event into a uint64\_t array.<br>Input arguments:<br>- **param**: key name.<br>- **value**: uint64\_t array reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.| 77|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<double>& value)|Parses the value of the **param** key in a system event into a double array.<br>Input arguments:<br>- **param**: key name.<br>- **value**: double array reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.| 78|int HiSysEventRecord::GetParamValue(const std::string& param, std::vector<std::string>& value)|Parses the value of the **param** key in a system event into a string array.<br>Input arguments:<br>- **param**: key name.<br>- **value**: std::string array reference.<br>Return value:<br>- **0**: Parsing is successful.<br>- **-1**: Parsing failed due to initialization error.<br>- **-2**: Parsing failed due to nonexistent key name.<br>- **-3**: Parsing failed due to type mismatch.| 79 80 81## How to Develop 82 83 84### **C++** 85 86The following provides an example of how to use C++ APIs of **HiSysEvent**. 87 881. Develop the source code. 89 Import the **DemoListener.h** header file, which contains the **DemoListener** class for implementing the custom event callback. 90 91 ``` 92 #ifndef DEMO_LISTENER_H 93 #define DEMO_LISTENER_H 94 95 #include "hisysevent_listener.h" 96 97 #include <string> 98 99 class DemoListener : public OHOS::HiviewDFX::HiSysEventListener { 100 public: 101 explicit DemoListener() : HiSysEventListener() {} 102 virtual ~DemoListener() {} 103 104 public: 105 void OnEvent(std::shared_ptr<HiSysEventRecord> sysEvent); 106 void OnServiceDied(); 107 }; 108 109 #endif // DEMO_LISTENER_H 110 ``` 111 112 Create the **DemoListener.cpp** file, and add the implementation logic of the custom event callback API in the **DemoListener** class. 113 114 ``` 115 #include "demo_listener.h" 116 117 #include <iostream> 118 119 void DemoListener::OnEvent(std::shared_ptr<HiSysEventRecord> sysEvent) 120 { 121 if (sysEvent == nullptr) { 122 return; 123 } 124 std::cout << sysEvent.AsJson() << std::endl; 125 } 126 127 void DemoListener::OnServiceDied() 128 { 129 std::cout << std::string("service disconnect, exit") << std::endl; 130 exit(0); 131 } 132 ``` 133 134 Call the **AddEventListener** API of the **HiSysEventManager** class to add a listener for system events. 135 136 ``` 137 auto demoListener = std::make_shared<DemoListener>(); 138 // Add a ListenerRule object based on the event tag, with RuleType left unspecified (in this case, ruleType is defaulted to WHOLE_WORD). 139 ListenerRule tagRule("dfx"); 140 // Add a ListenerRule object based on the event tag, with RuleType set as REGULAR. 141 ListenerRule regRule("dfx.*", RuleType::REGULAR); 142 // Add a ListenerRule object based on the event domain and event name, with RuleType set as PREFIX. 143 ListenerRule domainNameRule("HIVIEWDFX", "APP_USAGE", RuleType::PREFIX); 144 std::vector<ListenerRule> sysRules; 145 sysRules.push_back(tagRule); 146 sysRules.push_back(regRule); 147 sysRules.push_back(domainNameRule); 148 HiSysEventManager::AddEventListener(demoListener, sysRules); 149 ``` 150 1512. Configure the **BUILD.gn** file. 152 In the **BUILD.gn** file, add the **libhisysevent** and **libhisyseventmanager** libraries that depend on the **hisysevent_native** component. 153 154 ``` 155 external_deps = [ 156 "hisysevent_native:libhisysevent", 157 "hisysevent_native:libhisyseventmanager", 158 ] 159 ``` 160