Bookmark and Share

Recent Posts

IBM i Monitors: Automatic Notification and Replacement Variables

April 05, 2017

IBM Navigator for i (the web console) added support for message monitors and system monitors in the 7.2 release. For those of you familiar with Management Central monitors, the Navigator monitors are quite similar, however the underlying implementation is different.

This week I want to review the ability to use replacement variables when creating automatic notifications for your monitors. This information applies to both the Management Central monitors as well as the monitors in Navigator for i.

When you use monitors, the most significant value comes from the automation you add; it allows the system to notify you when a condition occurs, freeing you from checking on the system manually. I’m going to focus specifically on how to enhance the automation to include additional information when a threshold value is hit.

When you configure a metric in a system monitor, you add the automation by enabling a threshold and specifying the trigger (and optionally, reset) value, along with the duration for which the condition must persist. You then add an Operating System Command, which is the action you want taken when that condition occurs. The following screen capture shows the System Monitor Configure Metric panel:

For message monitors, this automation is added with the IBM i trigger command or the IBM i reset command, as the following screen capture shows:

Regardless of the type of monitor or the command used for your automation, you can extend your automation by using replacement variables. These replacement variables allow you to pass information to the command (which could be the CALL command).  

Here is a simple example:

I want to monitor the Average CPU Utilization for my IBM i production partition. If the Average CPU Utilization goes over 80%, I want to send a message to the QSYSOPR message queue because the system operator is always paying attention to the messages sent there.

If I did a simple message, the operating system command could be:
SNDMSG MSG(“Threshold triggered”) TOUSR(*SYSOPR)?
The system operator would know something happened, but would not have enough information to take the correct action immediately.

However, if I add replacement variables to my command, the operator would have much more information. For example:
SNDMSG ?MSG('Monitor &MON exceeded threshold &TVAL for &TDUR interval(s); current value is &VAL.') TOUSR(*SYSOPR)
Now the system operator will know which monitor (&MON) triggered, the trigger value (&TVAL) and duration (&TDUR), as well as the current value of the metric (&VAL).

Where do you find the documentation on these replacement variables?  That’s the super-secret trick … it is not documented in the IBM i Knowledge Center, but rather is located in the Navigator help. In the upper right hand corner of the Configure Metric window (for System Monitors) or the Message Set window (for Message Monitors), you will see a question mark:

Click the question mark for the Navigator help. Use the following drilldown to find the documentation on the replacement variables:
  • For System Monitors:
    • Threshold Trigger and Threshold Reset --> Parameters for Operating System Command
  • For Message Monitors:
    • Message Set 1 (or 2) --> IBM i Trigger Command --> IBM i Trigger or Reset Commands
For easy reference, I have copied the help information on replacement variables below:

System Monitor replacement variables:
You can use the following parameters for the operating system commands when the threshold for a system monitor is triggered or reset.  The parameters must be entered in uppercase exactly as shown.  See the examples below.
    Parameter    Passed Data
    &DATE        Date
    &ENDPOINT    Endpoint system name
    &INTVL        Collection interval
    &MON        Monitor name
    &RDUR        Reset duration
    &RVAL        Reset value
    &TDUR        Trigger duration
    &TIME        Time
    &TVAL        Trigger value
    &VAL        Current value

Message Monitor replacement variables:

Parameter Passed Data
&DATE Date (format MMDDYYYY)
&EVENTTYPE Event type (See note)
&FRMJOBNAME The name of the job that sent the message
&FRMJOBNUMBER The number of the job that sent the message
&FRMPROGRAM The name of the program that sent the message
&FRMUSER The name of the user that sent the message
&MON Monitor name
&MSGCOUNT The count of messages that caused the trigger
&MSGID ID of the message that caused the trigger
&MSGKEY 4-byte message key (as a hex string) for the message that caused the trigger
&MSGSEV Severity of the message that caused the trigger
&MSGTYPE Type of the message that caused the trigger
&OWNER User profile name of the user who owns the monitor
&THRESHOLD Threshold number that caused the trigger
&TIME Time (format HHMMSS)
&TOLIB The library containing the message queue to which the message was sent
&TOMSGQ The name of the message queue to which the message was sent

For further reference, find links below to prior blog articles I’ve written on Navigator System Monitors:

IBM i Navigator System Monitors: Collection Interval
IBM i 7.3 System Monitor Enhancements
New Monitor Metrics in 7.2
IBM i 7.2 - Navigator Monitors

Posted April 05, 2017 | Permalink

Post a Comment

Note: Comments are moderated and will not appear until approved

comments powered by Disqus