Using ^%SYSMONMGR to Manage Application Monitor

As described in Using the ^%SYSMONMGR Utility, the ^%SYSMONMGR utility lets you manage and configure System Monitor, including Application Monitor. The utility can be executed in any namespace, and changes made with it affect only the namespace in which it is started. You must maintain a separate Application Monitor configuration for each startup namespace you configure by starting ^%SYSMONMGR in that namespace.

Note:

Following any change you make to the Application Monitor configuration, such as activating a class, you must restart System Monitor in the namespace in which you made the change for the change to take effect.

To manage Application Monitor, enter the following command in the Terminal:

%SYS>do ^%SYSMONMGR

then enter 5 for Manage Application Monitor. The following menu displays:

1) Set Sample Interval
2) Manage Monitor Classes
3) Change Default Notification Method
4) Manage Email Options
5) Manage Alerts
6) Debug Monitor Classes
7) Exit
 
Option?

Enter the number of your choice or press Enter to exit the Application Monitor utility.

Manage Application Monitor

The options in the main menu let you manage Application Monitor as described in the following table:

Option	Description
1) Set Sample Interval	Sets the interval at which metrics are sampled; the default is 30 seconds. This setting can be overridden for an individual class by setting a class-specific interval (using the Set Class Sample Interval option on the Manage Monitor Classes submenu). Note: if the System Monitor sampling interval (see Set Sample Interval in the Set System Monitor Options submenu) is longer than the sampling interval for an Application Monitoring class, the longer of the two intervals is used. For example, if the System Monitor interval is 30 and the Application Monitor interval is 120, all active Application Monitor classes are sampled every 120 seconds; if the System Monitor interval is 60 and the %Monitor.System.LockTableOpens in a new tab class interval is 20, the class is sampled every 60 seconds.
2) Manage Monitor Classes	Displays the Manage Monitor Classes submenu which lets you manage system- and user-defined monitor classes in the namespace in which you are running the Application Monitor Manager.
3) Change Default Notification Method	Lets you specify the default action for alerts when triggered. Any alerts you create use this action unless you specify otherwise.
4) Manage Email Options	Displays the Monitor Email Options submenu which lets you enable and configure email notifications so you can specify this action in alerts.
5) Manage Alerts	Displays Manage Alerts submenu which lets you create alerts for system and user-defined monitor classes.

Manage Monitor Classes

This submenu lets you manage system and user-defined monitor classes. Enter the number of your choice or press Enter to return to the main menu:

Option? 2
 
1) Activate/Deactivate Monitor Class
2) List Monitor Classes
3) Register Monitor System Classes
4) Remove/Purge Monitor Class
5) Set Class Sample Interval
6) Exit
 
Option?

This submenu displays a list of menu items that let you manage the system- and user-defined classes as described in the following table:

Option	Description
1) Activate / Deactivate Monitor Class	Application Monitor samples active classes only. This option lets you activate an inactive class, or deactivate an active one. You can display a numbered list of the system and user-defined classes registered in the local namespace, including the activation state of each, by entering ? at the Class? prompt, then enter either the number or class name.
2) List Monitor Classes	Displays a list of the system- and user-defined classes registered in the local namespace, including the activation state of each.
3) Register Monitor System Classes	Registers all system monitor classes (except the %Monitor.System.HistorySysOpens in a new tab, %Monitor.System.HistoryPerfOpens in a new tab, and %Monitor.System.HistoryUserOpens in a new tab classes) and stores them in the local namespace. System classes must still be activated using option 1) Activate/Deactivate Monitor Class on this menu for sampling to begin.
4) Remove/Purge Class	Removes a monitor class from the list of classes in the local namespace. You can display a numbered list of the system and user-defined classes registered in the local namespace, including the activation state of each, by entering ? at the Class? prompt, then enter either the number or class name. Note: This option does not remove the class, but simply removes the name of the class from the list of registered classes that can be activated. To reset the list, choose option 3) Register Monitor System Classes on this menu.
5) Set Class Sample Interval	Lets you override the default Application Monitor sampling interval, specified by the 1) Set Sample Interval option of the Manage Application Monitor menu, for a single class. The default is 0, which means the class does not have a class-specific sample interval. See the description of the Set Sample Interval option for an explanation of precedence between this setting, the Set Sample Interval setting, and the System Monitor sample interval discussed in Set System Monitor Options.
6) Debug Monitor Classes	Displays Debug Monitor Classes menu which lets you enable and disable debugging as well as lists errors.

Debug Monitor Classes

This submenu lets you manage system debugging.

Debugging monitor classes adds the capability to capture any errors generated during the collection of sample values by user-defined Application Monitor classes.

Enter the number of your choice or press Enter to return to the main menu:

Option? 6
 
1) Enable Debug
2) Disable Debug
3) List Errors
4) Exit
 
Option?

The options in this submenu let you manage debugging for Application Monitor as described in the following table:

Input Field	Description
1) Enable Debug	Lets you enable debugging. If the class is not creating sample values, then you can check to see if errors are preventing the sample values from being saved.
2) Disable Debug	Lets you disable debugging.
3) List Errors	Displays the definitions of all errors in the local namespace; for example: %Save(), %New(), Initialize() and GetSample(). Enable debugging for the class using ^%SYSMONMGR, and the System Monitor will save the last error caught for specific methods within the class.

Input Field

Description

1) Enable Debug

Lets you enable debugging. If the class is not creating sample values, then you can check to see if errors are preventing the sample values from being saved.

2) Disable Debug

Lets you disable debugging.

3) List Errors

Displays the definitions of all errors in the local namespace; for example:

%Save(), %New(), Initialize() and GetSample().

Enable debugging for the class using ^%SYSMONMGR, and the System Monitor will save the last error caught for specific methods within the class.

Change Default Notification Method

When you create an alert, you specify an action to be taken when it is triggered; the default choice for this action is the default notification method, set using this option. Enter the number of your choice or press Enter to return to the main menu:

Option? 3
  
Notify Action (0=none,1=email,2=method)? 0 =>

The choice you make with this option is used when you configure an alert to use the default notification method, as described in the following table:

Input Field	Description
0	Do not take action when an alert is triggered.
1	Send an email message to the configured recipients when an alert is triggered. For information about configuring email, see Manage Email Options.
2	Call a notification method when an alert is triggered. If you select this action, the method is called with two arguments – the application name specified in the alert and a %List object containing the properties returned to the monitor class by the sample class (as described in Application Monitor Overview). When prompted, enter the full class name and method, that is packagename.classname.method. This method must exist in the local namespace.

Manage Email Options

The options in this submenu let you configure and enable email. When email is enabled, Application Monitor sends email notifications when an alert configured for them is triggered. Enter the number of your choice or press Enter to return to the main menu:

Option? 4

1) Enable/Disable Email
2) Set Sender
3) Set Server
4) Manage Recipients
5) Set Authorization
6) Test Email
7) Exit

Option?

The options in this submenu let you manage the email notifications for the Application Monitor as described in the following table:

Option	Description
1) Enable / Disable Email	Enabling email makes it possible for Application Monitor to send email notifications when alerts are triggered, if configured. Disabling email prevents Application Monitor from sending email notifications when an alert is triggered. Note: It is not necessary to reconfigure email options when you disable and then reenable email.
2) Set Sender	This option is required. Enter text identifying the sender of the email. Depending on the specified outgoing mail server, this may or may not have to be a valid email account.
3) Set Server	This option is required. Enter the name of the server that handles outgoing email for your site. If you are not sure, your IT staff should be able to provide this information.
4) Manage Recipients	This option displays a submenu that lets you list, add, or remove valid email addresses of recipients: 1) List Recipients 2) Add Recipient 3) Remove Recipient 4) Exit When adding or removing recipients, email addresses must be entered individually, one per line. Addresses of invalid format are rejected.
5) Set Authorization	Lets you specify the authorization username and password if required by your email server. Consult your IT staff to obtain this information. If you do not provide entries, the authorization username and password are set to NULL.
6) Test Email	Sends a test message to the specified recipients using the specified email server. If the attempt fails, the resulting error message may help you fix the problem.

Manage Alerts

An alert specifies:

a condition within the namespace that is of concern to you, defined by the values of properties sampled by a monitor class.
an action to be taken to notify you when that condition occurs.

To return to the previous example, you might create an alert specifying:

Condition: The lock table is over 90% full, defined by the UsedSpace property (returned when the %Monitor.System.LockTableOpens in a new tab class calls %Monitor.System.Sample.LockTableOpens in a new tab) being more than 90% of the TotalSpace property.
Action: Send an email notification.

The definition of a condition based on properties is called an evaluation expression; after specifying the properties of the sample class you want to use, you specify the evaluation expression. Properties are indicated in the expression by placeholders corresponding to the order in which you provide them; for example, if when creating the lock table alert you specify the UsedSpace property first and then the TotalSpace property, you would enter the evaluation expression as %1 / %2 > .9, but if you enter the properties in the reverse order, the expression would be %2 / %1 > .9.

When the alert menu displays, enter the number of your choice or press Enter to return to the main menu:

Option? 2
 
1) Create Alert
2) Edit Alert
3) List Alerts
4) Delete Alert
5) Enable/Disable Alert
6) Clear NotifyOnce Alert
7) Exit
 
Option?

The options in this submenu let you manage alerts for the Application Monitor as described in the following table:

Input Field	Description
1) Create Alert	Lets you define a new alert. For a description of the prompts and responses, see the Responses to Alert Prompts. The newly created alert is enabled by default.
2) Edit Alert	Lets you modify an existing alert. Enter the name of the alert to edit, or enter ? for a list of existing alerts and then enter a number or name. Note: You must respond to all prompts including those that you do not want to modify; that is, you must re-enter information for fields that you do not want to modify as well as the revised information for the fields you are modifying. For a description of the prompts and responses, see Responses to Alert Prompts.
3) List Alerts	Displays the definitions of all alerts in the local namespace; for example: Alert: LockTable90 USER Action: email Class: %Monitor.System.LockTable Property: UsedSpace,TotalSpace Expression: %1/%2>.9 Notify Once: True Enabled: Yes
4) Delete Alert	Lets you delete an existing alert. Enter the name of the alert to edit, or enter ? for a list of existing alerts and then enter a number or name. Note: Each alert must be entered individually; that is, you cannot specify a series or range of alerts to delete.
5) Enable / Disable Alert	Enabling an alert activates it. Disabling an alert deactivates it. Note: It is not necessary to reconfigure alert options when you disable and then reenable an alert.
6) Clear NotifyOnce Alert	Lets you set an internal Notified flag for a specified Alert name when the Alert is triggered. When set, it will not post another Alert.

The following table describes the valid responses to Alert prompts:

Responses to Alert Prompts

Input Field	Description
Alert Name?	Enter an alphanumeric name. To display a numbered list of alert names already defined in the local namespace, enter ? at the Alert Name? prompt.
Application?	Enter descriptive text to be passed to the email message or notification method. This text can include references to the properties you specify at the Property? prompt later in the procedure in the form %N, where %1 refers to the first property in the list of properties, %2 the second property, and so on.
Action (0=default, 1=email, 2=method)?	Specifies the action to take when the alert is triggered. Enter one of the following options: 0 – Use the notification method identified as the default method (none, email, or class method). See Change Default Notification Method. 1 – Send an email message containing your descriptive text and the names and values of the properties returned to the monitor class by the sample class (as described in Application Monitor Overview) to the configured email recipients when an alert is triggered. For information about configuring email, see Manage Email Options. 2 – Call a specified notification method with two arguments – your descriptive text and a %List object containing the properties returned to the monitor class by the sample class (as described in Application Monitor Overview). When prompted, enter the full class name and method, that ispackagename.classname.method. This method must exist in the local namespace.
Raise this alert during sampling? orDefine a trigger for this alert?	The first prompt is displayed when are creating an alert; the send prompt is displayed when you are editing an alert for which you entered No at the first prompt when creating it. Enter one of the following: Yes – Continues prompting for required information. No – Skips to the end, bypassing Class, Property and Evaluation expression prompts.
Class?	Enter the name of a system or user-defined monitor class registered in the local namespace. To display a numbered list of registered classes in the local namespace, including its activation state, enter ? at the Class? prompt, then enter a number or name. Note: You can create an alert for an inactive class. An alert is not removed when the class it is configured for is removed.
Property?	Enter the name of a property defined in the class specified in the preceding prompt that you are using in the evaluation expression, in the descriptive text, or in both.. To display a numbered list of properties defined in the named class, enter ? at the Property? prompt, then enter a number or name. Each property must be entered individually. When you are done, press Enter at an empty prompt to display the list of properties in the order in which you specified them.
Evaluation expression?	Expression used to evaluate the properties specified at the Property? prompt. For example, in (%1 = "User") && (%2 < 100), %1 refers to the first property in the list of properties, %2 the second property, and so on.
Notify once only?	Enter one of the following: Yes – Notify users only the first time an alert is triggered. No – Notify users every time an alert is triggered.

Application Monitor Metrics

Overview