AL Event Reports Syntax

Format

TYPE=AL  | CLASS=[owner-class-name . ] ... object-class
						| INSTANCE=[owner-class-name . ] ... object-name
						| SEV=severity
						| APPL=application-name
					[ | APPLQUAL=application-qualifier ]
						| ALERTID=alert-identifier
					[ | ALERTQUAL=alert-qualifier ]
					[ | HELP=help-file]
						| TEXT=alert-text
					[ | EXT_ACTION_LIST=action-list ]
					[ | attribute-name=attribute-value ] ...
					[ | _LOG=log-file-name ]

Note: The TEXT attribute is required when the event report raises, escalates, or de-escalates an alert; it is optional when the event report acknowledges or clears an alert.

owner-class-name

owner-class-name is a qualifier for any object that is not a system or server. Multiple iterations of owner-object-name are required for an object that is not a system or a server, and is not contained directly in a system. For example, If UNIX system A contains tape subsystem B, which contains tape drive C, the owner-class-name and object-class would be “A . B . C”. When an object-class or object-name contains qualification, the first segment of the qualifier must always refer to a system (or server).

object-class

object-class and object-name identify the system to which the alert applies. The class of a system can be any of the base classes, or any class derived directly or indirectly from one of the base classes.

For acknowledge and clear alert event reports, you can specify “all” for object-class, provided you also specify “all” for the object-name. Use “all” to acknowledge or clear alerts that apply to any system.

object-name

object-name is the name of the system. For systems managed by Operations Sentinel, the object-name must match the name that you specified for the system when you defined the systemusing Operations Sentinel Console. This is the systemfor which an alert is raised, acknowledged, or cleared.

For acknowledge and clear alert event reports, you can specify “all” for object-name, provided you also specify “all” for object-class. Use “all” to acknowledge or clear alerts that apply to any system.

SP-AMS Consideration [MCP, UNIX]

You can use the variable \_HOSTID\ to substitute the name of the systemthat sent the matched message.

CP-AMS Consideration [OS 2200]

The character strings $HOST$ and $CONSOLE$ have a special meaning when used as values of an object name. Operations Sentinel replaces these strings with the name of the system($HOST$) or console ($CONSOLE$) where the matched message originated.

severity

severity indicates whether an alert is to be raised, cleared, or acknowledged. If an alert is raised, severity indicates the severity of the alert.

Values for Raising an Alert

Severity values for raising an alert, in decreasing order of importance, are as follows:

Critical
Major
Minor
Warning
Informational
Indeterminate

These values are case insensitive. When a subsequent event report specifies a different severity for an outstanding alert, the alert is escalated or de-es.calated, as appropriate, and the check marks are removed from the “Seen and Acknowledge” columns in the Alerts window of Operations Sentinel Console.

Value for Clearing an Alert

“Clear“ is the severity value for clearing an alert. Clear indicates that you have resolved the alert condition. An outstanding alert with the same CLASS, INSTANCE, ALERTID, ALERTQUAL, and APPL is cleared, effectively deleting the alert from the Operations Sentinel server, and removing it from all displays in Operations Sentinel Console.

Value for Acknowledging an Alert

“Acknowledge“ is t he severity value for acknowledging an alert. Acknowledge indicates that you are acting to resolve the alert condition. An outstanding alert with the same CLASS, INSTANCE, ALERTID, ALERTQUAL, and APPL is acknowledged. It continues to be displayed in the Alerts window. If more than one instance of Operations Sentinel Console is running, the acknowledgment of the alert is displayed in each Alerts window.

When an alert is acknowledged, a check mark appears in the “Seen” column for it in the Alerts window in all instances of Operations Sentinel Console. This removes the highlighting from the alerts icon if it is the last unseen alert. A user can remove the check mark from the “Seen” column to highlight the alerts icon again in a specific instance of Operations Sentinel Console.

application-name

application-name is the name of the application program that sent the event report.

Alerts are associated with the application that raised them using the required attribute APPL and the optional attribute APPLQUAL. The application-name is the primary application identifier and indicates the source of the alert.

Alerts from SP-AMS [MCP, UNIX]

For alerts raised by SP-AMS, the meaning of the application name is slightly different. Run-time error conditions that SP-AMS detects are raised as alerts associated with application sp-ams. Therefore, it is recommended that alerts you raise using database EVENT-REPORT actions use a name other than sp-ams for application-name.

You may want to select a fixed application name, such as sp-ams-database to indicate that the alert was raised by a database action. Another possibility is to use the name of the database as supplied by the predefined variable \_DBNAME\.

However, the alert event report used to clear or acknowledge an alert must specify the same application name that was specified when the alert was raised. Therefore, if you use the database name as the application name, one database cannot clear or acknowledge an alert raised by another database.

application-qualifier

application-qualifier is a string that further qualifies the source of an event report. It is used typically to identify separate instances of the same application. For example, there may be more than one instance of an application running on one or more systems. In this case, the application developer could use the system-id (network name) and process-id of the application as the application qualifier. Unisys suggests the following format for an application qualifier:

system-id:process-id

A matching application qualifier is not required to clear, acknowledge, escalate, or de-escalate an alert.

[MCP, UNIX]

For alerts raised by SP-AMS, the meaning of the application qualifier differs slightly. There is only one instance of SP-AMS, so there is no need to further qualify the application. However, you might want to use this attribute to further qualify the source of the alert. For example, you might want to use the database name or the group ID and number of the pattern that raised the alert, or both.

[OS 2200]

For alerts raised by CP-AMS, the system and console are automatically identified in the Alerts windows, so it is not necessary to further qualify the application name. You might want to use this attribute to further qualify the source of the alert. For example, you might want to use the database name or the group-id and number of the pattern that raised the alert, or both.

alert-identifier

alert-identifier identifies or names the alert condition.

Any alert identifiers your data center specifies should not begin with an underscore (_). Unisys reserves alert identifiers that begin with an underscore to indicate condition]ns detected by Operations Sentinel.

The alert identifier is case sensitive and can contain spaces. If the HELP_TEXT attribute is not specified in an alert event report, the alert identifier is used as the default name for the alert help file. When an alert identifier is used as a help file name, spaces and the following characters in the identifier are converted to underscores:

/ \ : * ? “ < > |

Raising, Acknowledging, and Clearing Alerts

For raising, acknowledging, and clearing alerts, alert-identifier and alert-qualifier identify a specific alert condition. Only one instance of each alert condition can be active for a given object class, object name, and application name at one time. When you clear or acknowledge an alert, you must use the same alert-identifier, alert-qualifier, application-name, object-class, and object-name that you used when you raised the alert.

Clearing or Acknowledging Multiple Alerts

You can specify “all” as the alert-identifier for a clear or acknowledge alert request. In this case, all alerts for the specified object and application are cleared or acknowledged. When you specify “all” as alert-identifier, you must either specify no alert qualifier or “all” as alert-qualifier. You cannot specify “all” for this attribute in an event report that raises an alert.

It is the responsibility of each process that raises alerts to clear the alerts that it has raised. However, all alerts raised by event reports can be manually cleared in Operations Sentinel Console using the Alerts window.

Consider the following guidelines:

It is preferable to clear alerts automatically rather than the operator clearing them manually. This allows your site to move closer to an unattended operation.
An application program may fail or quit, but alerts that it raised remain outstanding. When such an application program recovers, the outstanding set of alerts may not be current. In this situation, you should consider clearing all alerts raised by the application and re-raising those alerts that still apply.

alert-qualifier

alert-qualifier is a data string that is used with the alert-identifier to further identify an alert. Since alerts can contain variable data, and multiple alerts can be associated with the same alert-identifier, you can use the alert-qualifier to identify the different message data.

Clearing or Acknowledging One Alert

When clearing or acknowledging a single alert, you must use the same alert-qualifier you used when raising the alert.

Clearing or Acknowledging Multiple Alerts

You can specify “all” for the ALERTQUAL attribute in a clear or acknowledge alert event report. In this case, all alerts for the specified object, application, and alert identifier are cleared or acknowledged. When you specify “all” as alert-identifier, you must either specify no alert qualifier or “all” as alert-qualifier. You cannot specify “all” for alert-qualifier in an event report that raises an alert.

help-file

help-file identifies the name of the file that contains the help text associated with an alert. If a file with this name is in the Operations Sentinel help text folder, the text in this file is included with the detailed information for the alert that can be displayed in the details pane of the Alerts window. You can store this file in a subfolder of the help text folder. In this case, separate the subfolder name from the help file name using four backslashes (\\\\) if the source is CP-AMS (for example, XPC-L\\\\42); or use two backslashes (\\) for other source names (for example, XPC-L\\42). If the file name is not valid or the file does not exist, the value of the attribute help-file is displayed as help text. Operations Sentinel does not treat this as an error condition.

Help Text Folder

The details pane in the Alerts window of Operations Sentinel Console lets you display help text associated with any alert displayed in the window. The help text is contained in a file in the help text folder. The name of this folder is data-folder\help\locale, where data-folder is the Operations Sentinel data folder on the Operations Sentinel server. By default, locale is C.

Each file in the help text folder contains help text. The help file contents are included automatically in the detail information for the associated alert. The text is indented three character positions. Text lines of about 50 characters tend to produce a visually appealing and readable display.

Help text for some alerts raised by Operations Sentinel is provided. See Appendix D, “Recommendations for Recovery from Catastrophic Failure” for information on customizing help text and defining additional help files.

HELP Attribute

When raising an alert, you can explicitly specify the name of a help file using the attribute HELP. If you do not specify the attribute HELP, the alert identifier (ALERTID attribute) is used as the file name.

Help Text File Names

Avoid using file names that conflict with the names of help files supplied with Operations Sentinel. Operations Sentinel uses an initial lowercase letter for its help file names. You can associate different help text files with the initial occurrence of an alert and subsequent escalation or de-escalation of the alert.

If a HELP attribute is not specified in the event report, the alert identifier is used as the help file name. The alert identifier is case sensitive and can contain spaces. However, when the alert identifier is used as a help file name, uppercase and lowercase letters are equivalent, spaces and the following characters are converted to underscores:

/ \ : * ? “ < > |

alert-text

alert-text is the alert text that is displayed in the Alerts window of Operations Sentinel Console. The Text attribute is required for raising, escalating, and de-escalating alerts, and is optional for clearing and acknowledging alerts. If the alert text spans more than one line, only the first line is displayed in the alerts pane of the Alerts window, followed by an ellipsis to indicate there is more. The full alert text is included in the detail information for the alert.

You can associate different alert text with the initial raising of an alert and subsequent escalation or de-escalation of the alert.

Formatting Multiline Text

To define multiline alert text, enter the correct number of escape characters (\) before the newline character (\n) as follows:

From spo_event, use the sequence \n.
From a program that is writing to spo_pipe, use a newline character.
From a shell command or script writing to spo_pipe, use the sequence \n.
[OS 2200, MCP, UNIX]
From an AMS database, use the sequence \\n.

Including a Backslash in Text

To include a backslash (\) in text, you must enter multiple characters, because a backslash has a special meaning in certain contexts.

From a program that is writing to spo_pipe, use a newline character.
[OS 2200, MCP, UNIX]
From an AMS database, use four backslashes (\\\\).

Using an incorrect number of escape characters can result in a truncated event report.

action-list

action-list is the name of an action list in the active alert policy. Alert policies are defined in the Administration mode of Operation Sentinel Console. See the Operations Sentinel Console Help for more information. The action-list identifies the actions to be executed when the alert is raised, acknowledged, or cleared.

When an operator manually clears an alert, the action-list value from the event that raised the alert is used.

If you do not specify the attribute EXT_ACTION_LIST in an event report, Operations Sentinel uses alert-identifier (the value of the attribute ALERTID) as the default value for the action-list.

The matching of action-list to the value EXT_ACTION_LIST or ALERTID is case insensitive.

You can associate different action lists with an alert when it is first raised and when it is subsequently acknowledged, cleared, escalated, or de-escalated.

attribute-name=attribute-value

Any additional attributes you specify in an alert event report are considered user-defined attributes. You may use these to specify any site-specific information you want.

Any attribute name you specify in an alert event report should not begin with an underscore. Unisys reserves attribute names beginning with an underscore for future use.

Operations Sentinel Console includes user-defined alert attributes in the detail information for the alert. You can display this information in the Details pane of the Alerts window.

log-file-name

This value specifies the log file to which information about this event report is written. If you do not specify a value (_LOG=), this attribute indicates that the event report is not recorded in any log file except SP-SPALS which records all AL event reports. The attribute enables a site to record different AL event reports in different log files.