Important This documentation space contains information about PATROL Agents when deployed in a TrueSight Operations Management environment. If you are a BMC Helix Operations Management user, see PATROL Agent 22.3.01 for BMC Helix Operations Management.

Defining event descriptions

You can modify standard event descriptions to provide information in the context of your environment. Thus, the event descriptions are more meaningful. You can do this by using the EventRules configuration variable (see Setting event rules) or by using Agent macros in a custom event catalog. This topic details the following information:

Using agent macros

If you are writing a new KM, insert an agent macro in the event description. If you are customizing an existing KM, define the Substitute Event Rule and then add an agent macro to it. Agent macros are expanded to the actual agent value at event publishing time. You specify the formal arguments and agent macros for an event in the event class.

Example

In the custom event catalog "MY_KM", event class "MyClass" defines a description template as: "On host %{HOSTNAME}%, at time %{TIME}%, alert on '%s' from %s parameter '%s' cancelled; exception no longer exists.". In this example, 3 formal string arguments are "alert on '%s' from %s parameter '%s' cancelled; exception no longer exists." and the two agent macros are "%{HOSTNAME}%" and "%{TIME}%".

You must specify the 3 actual arguments for publishing time as:

event_trigger("MY_KM","MyClass", ## class "MYclass" from the "MY_KM"
 event catalog "ALARM","3", ## ALARM and numerical severity of 3 "arg1", "arg2", "arg3"); ## actual argument to the event

The resulting event description will be "On host maxpc, at time 18:48:30, alert on '%s' from %s parameter '%s' cancelled; exception no longer exists." Note that the event trigger does not pass an actual argument to expand the agent macros. The agent does it automatically.

List of macros

You can use the following Agent macros to modify your event descriptions:

List of agent macros

Agent macro

Description

%{AGENT_VERSION}%

PATROL Agent version (example, V3.5.00)

%{ALARM_MAX}%

Upper threshold of current alarm range (example, 100)

%{ALARM_MIN}%

Lower threshold of current alarm range (example, 90)

%{APPCLASS}%

Application Class Name (example, ORACLE)

%{APPINSTANCE}%

Instance Name (example, PROD1)

%{AVE10}%

Average of last 10 Parameter Values (example, 3.00)

%{DATE}%

Date of Alert (MM/DD/YYYY)

%{EVENT_CATALOG}%

Event catalog name of originating event (example, 0)

%{EVENT_CLASS}%

Event class name of originating event (example, 11)

%{EVENT_ID}%

Event Manager's Event Id for the alert (example, 8765)

%{EVENT_SEVERITY}%

Event severity of originating event (example, 4)

%{EVENT_STATUS}%

Event status of originating event (example, OPEN)

%{EVENT_TYPE}%

Event type of originating event (example, ALARM)

%{HOSTNAME}%

Computer name

%{ICON_NAME}%

Instance Icon Name (example, PROD1)

%{IPADDRESS}%

IP Address (example, 192.168.1.1)

%{INSTANCE_NAME}%

Instance display name (example, MEMORY)

%{LAST10}%

Last 10 Parameter Values (example, 1.00 2.00 3.00 4.00 and so on.)

%{LAST10TP}%

Overall Time Period, in minutes, of LAST10 (example, 50.00)

%{LAST10TS}%

Last 10 Parameter Time stamps (example, 957359389 957359395 and so on.)

%{LOOKUP:/<prefix>/<varname>}

Values of customid1 and customid2

%{OS_TYPE}%

Operating System type (example NT, SOLARIS)

%{PARAMETER_NAME}%

Parameter Name (example CPUBusy)

%{PARAMETER_STATUS}%

Parameter Status (example ALARM,WARN,OK)

%{PARAMETER_VALUE}%

Parameter Value (example, 99.65)

%{PARENT_INSTANCE}%

Parent Instance Name (example, /ORACLE/ORACLE)

%{TCP_PORT}%

Agent's TCP listening port (example, 3181)

%{TIME}%

Time of Alert (HH:MM:SS)

%{TIMEZONE}%

Time Zone on affected System (example, 'US/Eastern/EDT')

%{UDP_PORT}%

Agent's UDP listening port (example, 3181)

Note: Not valid for PATROL Agent version 3.9.00

%{USERDEFINED}%

Value of variable '/_my_%APPCLASS%_%APPINSTANCE%_%PARAMETER_NAME%'

The following macros cannot be expanded by the agent:

Macro

Description

%{CUSTOM_ID1}%

Custom identifier assigned to object

%{CUSTOM_ID2}%

Custom identifier assigned to object

%{NOTIFY_EVENT_ID}%

Event Manager's event id for the NOTIFY_EVENT (example, 5439)

%{NOTIFY_EVENT_STATUS}%

Event Manager's event status of the NOTIFY_EVENT (example, OPEN)

%{NOTIFY_EVENT_TYPE}%

Event Manager's event type of the NOTIFY_EVENT (example, ALARM)

Note

The LOOKUP macro will not work for event catalogs.