Differences

This shows you the differences between two versions of the page.

--- guides:reference:system_events:events_configuration [2020/03/24 16:13] – [Attributes explained] yspeerte
+++ guides:reference:system_events:events_configuration [2024/07/03 12:31] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
+{{indexmenu_n>1}}
+===== System Events configuration =====
+The System Events configuration file is ''**system_events.conf**'' and its customizable copy resides in ''/opt/yce/etc''. If it is missing the distribution version located in ''opt/yce/system'' is copied to the ''etc'' directory.
+This configuration file consists of two parts, the top section defines the events and what effect they have. The second part defines the event signal types. This article explains the top section.
+The file is formatted in the Perl syntax and contains the definition of the two hashes making up the aforementioned sections. The ''**system_events**'' hash has the attributes associated with the events coming from the various system monitors.
+This hash has three levels, the first level is referred to as the //CLASS// of the event, the second level its //STATE// and the third level has the various //ATTRIBUTES// and values for the event state. There is a structure like this for every System event that is generated by one of the monitors.
+<code>
+#------------------------------------------------------------
+# CLASS  STATE  ATTR          VALUE
+# db_conn_state => {
+#        name =>              connection_status  # the 'database_name' this class is mapped to
+#        error => {                              # defines the 'high' state setting for this class
+#               msg_type =>   3                  # message will show at pre-login (1), post (2) or both (3)
+#               severity =>   4                  # event impact (and color) as set in lookup
+#                                                # 0=clear, 1=low .. 4=high
+#               user_level => 2                  # minimum user-level to display message
+#                                                # 0=everyone, 1=browser .. 5=manager
+#               signal_type => 'syslog, trap'    # none | syslog | trap | email | rest-api
+#               signal_int =>  120               # interval in seconds to repeat event, 0=once
+#------------------------------------------------------------
+</code>
+==== Attributes explained ====
+As Events are generated by the monitors, three vales are passed into the System Events. \\
+The first is the CLASS of the event. This is the internal name of the monitor. In the example above it is the ''db_conn_state''. \\
+The second is the STATE of the event. Its value depends on the monitor and what states it can be in. In the example is shown the ''error'' state. As this specific monitor reports on the connection status to the database the state can have three values: 'error', 'switch', and 'clear'. These correspond to the 'no database connection', 'switched to the secondary database' and '(re-)established database connection to primary'. \\
+The third and last value of the event is the message. This message will be used in the notifications and signalling to inform what the event is all about.
+The customization of the events in this configuration will usually only affect the attributes of the event. They specify for who, where and how the notifications are displayed and which signalling takes place. As these attributes are defined per monitor and per state, the event notifications can be tailored to a high degree.
+^  Attribute  ^Example  ^Description^
+|**msg_type**|3|The message-type determines if the notification-bar will show the event on the login screen (1) only, after login (2) only, or both (3). \\ When events are to be displayed before login it will be displayed for all users, the user_level setting has no effect before logging in|
+|**severity**|4|The numeric value of the severity-level of this event is used to perform a lookup to find the severity name and colour of the severity. See the paragraph below on "Severity customization".|
+|**user_level**|2|Not all messages are useful for all users. Some are relevant only for 'manager'-level users where others are also relevant for 'engineer'-level users. The user-level attribute  defines the lowest user-level that will get the notification. These levels correspond to the NetYCE operator levels|
+|**signal_type**|'syslog,email'|The value is either 'none' for no external signalling or a string with one or more of the values: syslog, trap, email, rest-api. In the example the signalling will send out syslog(s) and an email if this event occurs|
+|**signal_int**|1800|When this value is set to '0', the signals are sent only once for this event. To get periodic signals when the state is still unchanged, set it to the number of seconds to receive a 'reminder' of the event. The signalling interval is the same for all four signalling types.|
+==== Class mapping ====
+One additional setting in the Events configuration has been ignored - up to now. The ''**name**'' attribute at the 2nd level plays an important role in the way event monitors can be combined to form a single status. This ''name'' value is what the CLASS name will be translated to to form the notifications and signalling.
+Where ''db_conn_state'' is the name of the monitor, the events will set the ''connection_status'' events. And similarly will the class ''db_sync_state'' generate ''replication_status'' events. Thus we get two distinct statuses for the DB connection and the DB replication. For these two monitors that was the way it was designed but for other monitors for e.g. cpu and disk usage these could very well be combined in a single event status for 'system resources'.
+It is suggested not to modify these monitor class to event status mappings unless there is good understanding of the various states each monitor produces.
+==== Severity customization ====
+By default four severity levels exist to assign to System events: 'Low', 'Medium', 'Serious', and 'High'. A fifth, 'OK', should be considered a reserved value indicating all is 'ok'.
+Using the 'Admin - Lookup' tool, these levels can be customized and extended as required. The entries using variable ''Status_bar_severity'' and class ''Translation'' are used to assign the severity level number to its name (3 -> Str_value='Serious') and its notification color (3-> Str_balue_b='#ff8800'). Both values can be modified as can the number of severities.
+The severity numeric value is used to assign to the ''severity'' attribute value in the configuration file section for the system_events.
+{{ :guides:reference:system_events:sys_events_severity.png?nolink&800 |}}
+==== Syntax check ====
+**CLI changes** \\
+After making modifications it is recommended to check the syntax of ''system_events.conf'':
+<code>
+$ cd /opt/yce/etc
+$ go chk system_events.conf
+-- perl -cw current dir
+system_events.conf syntax OK
+</code>
+**System configuration tool** \\
+If changes to the configuration file were made using the 'Admin - System - Edit configs' tool, the syntax is automatically checked for errors. Only when the file syntax is valid will the file history be updated and the configuration be activated.
+Since most system-monitoring is performed by the ''**yce_skulker**'' daemon, this process needs to be restarted after changes to the configuration were made. This can be done on the cli (''go restart skulker'') or by clicking the ''Stop yce_skulker'' button in the 'Admin - System status' tool. It will be restarted automatically by the process monitor daemon (yce_psmon) within 20 seconds.