Defining events

In software applications, monitoring system performance is often a key administrative task. This monitoring is often manifested in the creation and viewing of events.

Events ("alarms") can refer to specific objects (relevant to IBM WebSphere MQ only) within the managed system or to the system as a whole. Typically, they are graded or ranked by severity. See Rule types: definitions and variations for further information.

In TrueSight Middleware Administrator, events are defined as one of two types: active or reset events. Events triggered by rule definition conditions are active events until the conditions of their activation no longer pertain. At that point, they become reset events.

To differentiate between these event types:

• Active events reports and displays all events for which the triggering condition applies (for as long as it applies).
• Reset events are active events for which triggering conditions no longer apply. The reset event recounts the event's history.

An active event is produced when parameters or thresholds for a specific rule type definition are surpassed a specified number of times. Active events are triggered when associated rule conditions are fulfilled (thresholds surpassed).

The Product Administrator decides on the severity of an event. The event then appears in a warning or critical state when any user selects the Events option from the Global Actions Bar.

Active events have a life span. Once the conditions (defined in WMQ Events Rules definitions) that prompt an event no longer pertain, the event is cycled to reset event status. This is a history of events that have passed out of the active state.

Events configuration is a two-part procedural process:

• Enabling monitoring (per connection)
• Configuring events rules (per project)

Enabling connection monitoring

Events configuration requires that monitoring first be enabled for the connections that are assigned to projects.

To enable monitoring for a connection (one that is associated with a project for which you configure events):

1. Select the WMQ Connections object from the Navigation Panel.
2. View current IBM WebSphere MQ queue managers.
3. Select the queue manager for which you wish to enable monitoring.
4. Look at the Properties page and confirm that the Monitoring Enabled checkbox is selected. If not, select it.
5. The connection update is saved and the WMQ Connections Summary View is displayed.

Rule types: definitions and variations

Multiple rule types exist in TrueSight Middleware Administrator. These belong to different groups of rules with similar purposes.

• Queue more than N percent full
• QMgr not accessible
• Message in DLQ
• Queue Full
• Command Server Down
• XMT queue not serviced
• Channel retrying and XMIT queue not empty
• Channel retrying
• Channel in doubt
• Channel stopped (as in our configuration example)
• Queue has more than N msgs
• Queue has more than N msgs and no readers
• Queue is more than N percent full and has no readers
• Queue has less than N readers
• Queue has less than N writers
• Server conn channel has more than N running instances
• Total running channel count is more than N
• XMIT queue has more than N msgs
• XMIT queue is more than N percent full
• First message on queue waiting more than N seconds
• Oldest message on queue waiting more than N seconds
• Oldest message on XMIT queue waiting more than N seconds
• Trigger monitor is not running
• Channel initiator is not running

Viewing events

To view active or reset events, simply choose the events option from the Global Actions Bar. All active events are shown by default. The following view fills the workspace:
 
In the example above, nine events are displayed for two IBM WebSphere MQ queue managers. Five are critical in nature. Four are warning events. On the first queue manager, you can see events of both types.

Viewing reset events

While active events are displayed automatically on selection of the events option from the Global Actions Bar, you must take another step to view the reset events. As a reminder, these are summaries of events that are no longer active (for which triggering conditions no longer hold).

To view reset events:

1. First select the events option from the Global Actions bar.
2. Any current active events are displayed.
3. Select Show Reset Events. The workspace changes accordingly.
4. Select the + icon next to any specific event to expand the display. When you do, the Reset Event details are displayed.
5. Use the horizontal scroll bar to view all event details.

Defining event rules

Refer first to the Rule types: definitions and variations section above if this is the first time you are defining event rules.

To define events for a project:

1. Select Projects from the Navigation Panel, and then a specific project. The Project Properties Editor is displayed.
2. Open the WebSphere MQ Events Rules section settings.
3. Select the Create Events Rule (Add item) icon. Note how the WMQ Events Rules space fills with rules types definitions (parameters), as seen in the image below.
   The first rule in the drop-down list is populated in the rules type fields. You can select any rule type more than once by giving each rule a unique name. Keep in mind that each rule type defined refers to one potential active event. Refer to the Rule types: definitions and variations section above for details.
   
4. Select a Rules Type from the pull-down list to configure. In this case, we work with the rule type Queue more than N percent full. Each rule type has its unique set of parameters. Queue more than N percent full parameters populate the rule types fields.
5. Type a rule name in the Rule Name field. Choose a name that is descriptive of the rule type.
6. Set the rule State; this can be either Warning or Critical. The setting relates to the importance of the event to system performance. We set the rule type in this example to Critical, since it is reporting a failed state.
7. Define a connection name. This accurately describes the project connection to which the rule applies.
   You can also apply wildcard definitions to apply the rule to multiple connections. To apply to all connections in the project, use *.  To apply to all connections that start with PROD, use 'PROD*', and so on.
8. Define a number of occurrences [surpassing the threshold] before the event is activated. Remember that we have defined this as a critical rule. Given that, we set 1 as the number of times the condition (channel stopping) occurs before triggering an active event.
9. Set an object name as desired. This field exists to allow inclusion of 'child' objects of connections - it includes them within the rule.
   You could create an individual rule to apply to only system objects  - object name = "SYSTEM.*" and different rules for "APP*", "PROD*", etc. or a specific queue name. You can also exclude object names, to exclude these objects from the configured rule and related event/notification. For instance, if you set * to include all objects, you would exclude system objects by entering 'SYSTEM.*'
10. Optionally, set actions to occur when the configured event is triggered. These are described in detail in Configuring monitoring.
    The actions available are 1) sending an email notification on event occurrence, 2) executing a script in response to the event:
    1. To activate email notification, select the E-mail option and enter a required email address in the text box below. Multiple emails can be added by separating them with a semi-colon. Note that the SMTP section in Settings must be configured for email notifications to work; see the SMTP settings section in Configuring monitoring for further information.
    2. To execute a script, select the Execute Script option. Define the script in the text entry box below Execute Script.
       An Execute Script can be any command line script or program on the system where the TrueSight Middleware Administrator server is running. You must specify either the relative path from the TrueSight Middleware Administrator installation directory, or the full path to the script or program. If using a relative path, you must start the path with ./ on Linux and .\ on Windows. 
       If you need to specify arguments to the script or program, you will need to use another command line script that will call the target script or program with the required arguments and specify the wrapper script in the event rule definition. 
       If TrueSight Middleware Administrator is running as a high availability configuration, the Execute Script specified will be issued on each system that is in the high availability configuration. Note that when triggered, the script will execute from TrueSight Middleware Administrator's working directory, which is the installation directory.
       You can rerun any configured event response if the event remains active for 'x' minutes. Set the parameters for repeating the configured response in the adjacent scrollable box. How often an action is re-run can also depend on the monitoring interval (see the Monitoring settings section in Configuring monitoring), which determines when the Event service is evaluating event rules and executing actions.
11. The final editable parameter is Rule effective day and time. Unless you set it, the rule will be inactive.
    1. First, set the days on which the rule is active and the related event produced. All days are default-checked. For any day that you disable, the configured event occurrence is similarly disabled.
    2. Set the Start and End times for application of the rule. You can reduce or increase the number of hours to activate the rule.
       Start and end time defaults are in 15 minute increments, but you can change the time periods to reflect any number of minutes.
12. Save the rule by clicking on the Save button at the bottom of the rule.

To edit event rules:

1. From the WebSphere MQ Events Rules section, click the relevant rule to edit.
2. Modify any of the rule settings, as described in the previous procedure.
3. Save the rule by clicking on the Save button at the bottom of the rule.

To remove event rules from a project:

1. From the list of displayed event rules, click the relevant rule to remove.
2. Scroll down and click Delete.
3. Save the project by clicking the Save icon.