Creating, raising, and finding custom defined events

The user can create and raise custom health events in IBM Storage Scale, which can be displayed by using the mmhealth node eventlog command. You can also view these events in the IBM Storage Scale GUI, under Monitoring > Events.

To raise a custom event, the event must first be created, and the health daemon must be made aware of the existence of the custom event. Follow these steps to create and raise a custom event:

1. Create a /var/mmfs/mmsysmon/custom.json file and create a symlink to this file under /usr/lpp/mmfs/lib/mmsysmon/.
   This ensures that an upgrade or rpm delete does not remove this file. The file needs to include the custom events in a .json format as shown:

   
   {
   "event_name_1":{
          "cause":"",
           "user_action":"",
           "scope":"NODE",
           "code":"cu_xyz",
           "description":"",
           "event_type":"INFO",
           "message":"",
           "severity": ["INFO" | "WARNING" | "ERROR"]
    },
    "event_name_2":{
           […]
   }

   Note: You might need to re-create the symlink after an update.

   When you create an event in the custom.json file, ensure that the event name is unique and it is specified in lowercase. Only the events that are specified in lowercase are displayed in the GUI.

   You can also fill the cause, description, and message with descriptive text. The message can include place holders in the form of n, where n is an integer value. These placeholders are filled with arguments that are provided at the time of raising the event. A new line (\n) must not be included in the message.

   The code must be a unique alphanumeric value that does not exceed a length of six characters. It is recommended to use a form like cu_xyz, where xyz must be replaced with a unique number. If there is a duplication in the codes, the daemon throws an error and does not load the custom.json file. The GUI ignores the events if the ID is longer than six characters. Using this format ensures that there is no collision with the system-provided events after an update of the gpfs.base file.

   Note: While the severity can be set as INFO, WARNING, or ERROR, event_type must be set to INFO.
   For example:

   
   [root@test-21 ~]# cat /usr/lpp/mmfs/lib/mmsysmon/custom.json
   {
     "event_1":{
          "cause":"cause text",
           "user_action":"user_action text",
           "scope":"NODE",
           "entity_type":"NODE",
           "code":"ev_001",
           "description":"description text",
           "event_type":"INFO",
           "message":"message with argument {0} and {1}",
           "severity": "INFO"
     }
   }

2. Restart the health daemon using the systemctl restart mmsysmon.service command.

   The daemon does not load the custom.json file if there are duplicated codes in the events. The daemon status can be checked using the systemctl status mmsysmon.service command.

3. Run the mmhealth event show <event_name> command, where <event_name> is the name of the custom event.
   The system gives output similar to the following:

   
   [root@test-21 ~]# mmhealth event show event_1
   Event Name:              event_1
   
   Description:             description text
   Cause:                   cause text
   User Action:             user_action text
   Severity:                INFO
   State:                   Not state changing

   If the custom.json file was loaded successfully, the command returns the event's information. If the custom.json file was not loaded successfully, an error message is displayed stating that this event is not known to the system.

4. Repeat steps 1-3 on all nodes.
5. Restart the GUI node using the systemctl restart gpfsgui.service command to make the GUI aware of the new events.
6. Run the following command to raise the custom event:

   mmsysmonc event custom [<event_name> | <event_code>] <arguments>

   The system gives output similar to the following:

   
   [root@test-21 ~]# mmsysmonc event custom event_1 "arg1,arg2"
   Event event_1 raised
   [root@test-21 ~]# mmhealth node eventlog
   Node name:	test-21d.localnet.com
   Timestamp                             Event Name                Severity   Details
   2018-07-30 10:07:08.404072 CEST       eventlog_cleared          INFO       On the node test-21d.localnet.com
                                                                              the eventlog was cleared.
   2018-07-30 10:07:20.228457 CEST       event_1                   INFO       message with argument arg1 and arg2
   

   Note: You can raise a new custom event only after you restart the gpfsgui and mmsysmon daemon. The <arguments> needs to be comma-separated list enclosed in double quotation mark. For example, “arg1,arg2,…,argN”.

   You can use the mmhealth node eventlog command to display the log of when an event was raised. You can also configure emails to notify users when a custom event is raised. For more information, see Event notifications.