PATROL events

This topic provides information on PATROL events.

Inside the PATROL product, an event is any kind of asynchronous information generated by the PATROL Agent. An event is created when any monitored object changes state or the PATROL Agent detects any condition that is noteworthy or an event is explicitly generated by a PSL script. In addition such actions as a PATROL Console connecting to the PATROL Agent or a PSL task executing are considered events. Many things can generate an event.

Events can be generated by the PATROL Agent, a PATROL Knowledge Module, another remote agent, or any application that uses the PATROL API.

Using criteria from both the Standard Event Catalog and from PATROL KM event catalogs, the PATROL Agent processes an event as part of monitoring and stores the event in an event repository. If the PATROL Agent is connected to the PATROL Event Manager, the PATROL Agent forwards the event to the PATROL Event Manager. The types of events forwarded by the PATROL Agent are controlled by a persistent filter set for each Event Manager/ PATROL Agent relationship.

Multiple consoles can share the same events, and an action applied to a given event is seen by other consoles monitoring the same PATROL Agent. For example, if two users are viewing the event log for the same host and one user acknowledges the event, this action appears in the both console windows.

An event belongs to a particular event class which defines properties that the event has and how the event is to be processed by the PATROL Event Manager. Event classes are defined in the PATROL Standard Event Catalog or in KM-specific (application class) event catalogs.

About the PATROL Event Manager (PEM)

The PATROL Event Manager (PEM) is a core component of the PATROL Agent architecture, providing agent level event management. The PEM engine manages events originating from the PATROL Agent, PATROL Knowledge Modules running on the PATROL Agent, or any event generating application that is connected to the PATROL Agent through the PATROL Cli or PEM API. The PATROL product offers various methods of accessing PEM data including through the PATROL Script Language (PSL) and through the PATROL API.

About the PATROL API

The PATROL API allows external components and user-written (non-PATROL) applications to interface with the PEM and perform actions including:

  • Generating an event
  • Closing, acknowledging, or deleting an event
  • Escalating an event to higher-level of visibility
  • Performing event queries

The PATROL API supports both advanced event-driven application management within PATROL KMs and event integration to third-party management frameworks. Each connection to the PATROL Agent has its own handle so the PATROL API can allow a non-PATROL program to connect to any number of PATROL Agents either on a single host or on multiple hosts. The network transport layer used by the PATROL API is compatible with UDP and TCP.

About PATROL event catalogs

You create events classes in event catalogs. The PATROL product has two types of event catalogs--the Standard Event Catalog and application class event catalogs. The following table summarizes the PATROL event catalog types.

PATROL event catalog types




Standard event catalog

Contains the predefined event classes for the PATROL product

Use the pre-defined event types in PATROL KMs.

Application event catalog

Contains event classes created for a specific application class.

Create new application class-related event types that set up event-driven processing.

PATROL standard event catalog

The PATROL Standard Event Catalog is the repository for the event class definitions that are available to the core PATROL product. It is a file named StdEvent.ctg that resides in a specific directory on each platform that PATROL supports: 

%PATROL_HOME%\lib\knowledge (Windows) 

$PATROL_HOME/lib/knowledge (UNIX)

Application event catalog

A PATROL application event catalog contains the event classes that used by a particular PATROL application class. You create an application event catalog in the Event Catalog folder for the application class.

About event classes

An event class is a class definition that describes the properties that an event of that class can have and how it is to be processed by the PATROL Event Manager. 

Each event class has the following properties:

  • General properties such as name, event type and category
  • Escalation command and its properties
  • Notification command and its properties
  • Acknowledge command and its properties
  • Expert Advice
  • Description

The following table summarizes event class properties:

Event class properties



General Properties

Basic information that defines the event class.

Escalation Properties

A command to be automatically executed if the event is not acknowledged, closed, or deleted within a specific time period.

Notification Command

A command to be automatically executed immediately after an event occurs.

Acknowledge Command

A command automatically executed only when the event is acknowledged by a user through either the PATROL Console or PATROLWATCH for Windows.

Expert Advice

A text string that provides an advanced description of the problem, possible solution, or message about the event class. This information appears in the Expert Advice pop-up of the PATROLWATCH Event Details dialog box.


A text string that is the event description that will appear in the Event Description field of the PATROLWATCH for Windows Console.

PATROL event types

A PATROL event type is the category of an event as defined by its event class. It is used primarily as a sorting filter in the PATROL Event Manager display. You can assign a PATROL event to one of the following event types:

PATROL event types

Event type



An event triggered by an alarm condition in a monitored object.


An event that cannot be filtered and always displays in any event list.


An event resulting from a failure or error.


An event that is logged for informational purposes only.


An event that is triggered by the state change of a monitored object.


An event triggered by an alert condition in a monitored object.


An special type of event used to synchronize PATROL Console response dialog box processing. The PATROL Agent triggers a RESPONSE event only at the request of the PATROL Console when a response dialog box is displayed.

Object versus the STATE_CHANGE action

Object action events are defined as the Standard Event Catalog Event types that have a Message Type of WARN, ALARM, or INFO and include description text of the format: 

"STATE_CHANGE:" <old> <new> 

where the value of <old> is the original object state and the value of <new> is the current object state. 

These object action events should not be confused with the STATE_CHANGE event which does not include the word STATE_CHANGE in its description.

Event class commands

Each PATROL event class can have the following event commands defined:

Using event class commands

Command type


Use to

Notification command

An event class command that is executed immediately after the event occurs.

  • Set up event-driven processing
  • Send event notification to a third-party console.

Escalation command

A command to be automatically executed if the event is not acknowledged, closed, or deleted within a specific time.
When an event is escalated, the PATROL product performs the following actions:

  • Adds an entry in the Event diary
  • Changes the event's status to ESCALATED
  • Executes the event's escalation command if one is associated with the event's class

Send an email or page to the group or person responsible for taking action.

Acknowledgment command

A command to be automatically executed only if the event is acknowledged by the user in a PEM console.

Send an email or page to the group or person responsible for taking action notifying them that the event is under investigation.

You can define a generic message in the event class description for an event class. Using the event-related PATROL built-in variables, you can build a generic event class description that gives the user the critical information about the event. The description will appear in a PEM console.

How PATROL events are triggered

PATROL events are triggered automatically whenever an state change occurs. PATROL events also can be triggered explicitly by the PSL event_trigger() and event_trigger2() functions. These functions allow you to trigger an event of a specific event class, assign a severity to it, and perform event-driven processing through the event Notification command.

 Event severity

Although severity is not an event class property, an event instance can have a severity value to indicate how serious the event is. Event severity can be assigned to an event through the PSL event_trigger() and event_trigger2() functions. Event severity can be an integer value between 1 and 5, with a value of 5 indicating the most serious events. Event severity is used as a filter to limit the events that display in an event management console to only those of equal or greater severity than the specified filter.

How PATROL processes an event

The following figure shows how the PATROL Agent processes a PATROL event and its associated commands. On detecting a condition, the PATROL Agent starts an event timer and schedules execution of any commands associated with the event's event type. If a notification command is defined, it is executed immediately after the event occurs. You can create notification commands to do the following things:

  • Send messages
  • Take corrective actions

Next, if the escalation period lapses without being acknowledged, the PATROL Agent does the following things:

  • Changes the event's status to escalated
  • Adds an entry to the PEM event diary, if a PEM console is connected
  • Executes the escalation command, if one is defined for the event class. An escalation command is used to escalate an event's visibility.

Finally, if an acknowledgment command is defined for the event class, it is executed only when the event is acknowledged by a user through a PEM console. An acknowledgment command can be used to silence alarms. 

The only way that an event can cause action is through its Escalation, Notification and Acknowledge commands specified in the event's class definition. 

 Event processing logic 

About messages and event classes

As described in the following table, event classes have three built-in features that allow you to propagate information about an event to users: 

Event class messaging options




To display a dynamically formatted user message describing the event in a PEM console. You can build the description using the PATROL built-in variables. When the event is triggered the appropriate values are substituted similar to the C language printf() function.

Expert advice

To display a static description of the problem, possible solution, or message about the event class in a PEM console.

Notification command (Windows only)

A script that executes immediately when an event of the associated event class is triggered. Common Notification command actions include paging a person or group of persons or sending email to a person or group of persons.

Was this page helpful? Yes No Submitting... Thank you