BMC ProactiveNet Performance Management Tech Note
PATROL Agent 9.0 Event Format and Filtering Rules
07/27/2012
H. Meeks with content from G. De Peuter
Overview
PATROL agent versions 9.0 and higher include an event forwarding capability that sends events directly
to a BPPM event management processing cell. This capability is built into the agent and does not
require additional KMs like the Event Management KM. The related event pre-processing capabilities in
the PATROL agent are very robust and include event formatting, filtering, supports list of values used in
event slots, persistency and leverages agent macros. This document covers these topics through
examples.
Event Formats
Event formats are stored in PATROL pconfig rule sets. The event format for BiiP3 is delivered out of the
box. The event format allows activation or deactivation (filtering) through pconfig and PATROL
Configuration Manager.
The “key/value -pair” in the pconfig database is shown below.
/EventSetup/Format/BiiP3/catalogs/<KM name or 0>/types/<Event Class>/slots/<slot>
= <value>
“value” can contain macro variables including the powerful LOOKUP macro that is available in the
PATROL agent.
There are built in slots and built in branches.
-
Class slot – This slot contains the event CLASS which is used for triggering the event. If CLASS is
not specified, the event CLASS “EVENT” is used.
ACITVE slot – This slot may contain 1 or 0, to enable or disable the event. The value 1 enables
event generation. The value 0 disables event generation. Both cases apply to the criterion
specified in the variable.
Here is an example rule set that defines a format:
/EventSetup/Format/BiiP3/class = “PATROL_EV”
/EventSetup/Format/BiiP3/catalogs/0/types/11/slots/p_application = %{EVENT_CLASS}
/EventSetup/Format/BiiP3/catalogs/0/types/11/slots/p_instance = %{EVENT_INSTANCE}
/EventSetup/Format/BiiP3/catalogs/0/types/11/slots/mc_origin_class = “PATROL Agent”
If the above is the complete definition then triggering event class 11 of standard event catalog will result
in the following BAROC event:
PATROL_EV;
p_application = “MYKM”;
p_instance = “MYINST”;
mc_origin_class = “PATROL Agent”;
END
The mc_origin_class is used for all PATROL events.
You can define default slots for the event format as shown in the example below.
/EventSetup/Format/BiiP3/class = “PATROL_EV”
/EventSetup/Format/BiiP3/slots/p_application = %{EVENT_CLASS}
/EventSetup/Format/BiiP3/slots/p_instance = %{EVENT_INSTANCE}
/EventSetup/Format/BiiP3/slots/mc_origin_class = “PATROL Agent”
With these defaults, every triggered event will inherit the specified slots and will use the default event
class “PATROL_EV”.
Defaults can be applied at the KM level or specifically for the StdEvent Catalog as in the example below.
/EventSetup/Format/BiiP3/catalogs/0/slots/p_catalog = 0
The user can specify the event format configuration. This is done using the rule settings shown below.
/EventSetup/Configuration/Format = <format>
This allows users to quickly change formats – create their own and test with it.
Active / Inactive Filtering
There is an attribute in the slot list that indicates if events will be active (sent) or not. This is the ACTIVE
slot. The BPPM event processing cells include an “unwritten rule” assuming classes should be all caps
and slots should be lowercase – this convention does not cause conflicts.
Assuming all slots are defined in the default definition for the BiiP3 format show above in the Event
Formats section the following example will disable sending events of class 0, type 11.
/EventSetup/Format/BiiP3/catalogs/0/types/11/active = 0
The ACTIVE evaluation is processed from “root” to leaf with the following precedence (low to high).
1. /EventSetup/Format/BiiP3/active
2. /EventSetup/Format/BiiP3/catalogs/0/active
3. /EventSetup/Format/BiiP3/catalogs/0/types/11/active
The ACTIVE determination/Filtering algorithm is very intuitive.
-
If ACTIVE on the root level is missing – we assume the event is ACTIVE – so not specifying ACTIVE
at the root level is the same as ACTIVE = 1 at the root level when a more specific rule is appied.
Propagation of the ACTIVE flag follows normal inheritance rules like it does for all the other
attributes.
Consider the following examples (assuming these are the only active settings present in the agent).
Send only Standard Events, except for event 11:
1. /EventSetup/Format/BiiP3/active = 0
2. /EventSetup/Format/BiiP3/catalogs/0/active = 1
3. /EventSetup/Format/BiiP3/catalogs/0/types/11/active = 0
Send no Standard Events:
1. /EventSetup/Format/BiiP3/catalogs/0/active = 0
Send only Standard Event type 11:
1. /EventSetup/Format/BiiP3/active = 0
2. /EventSetup/Format/BiiP3/catalogs/0/types/11/active = 1
Send all events, except for standard event 11:
1. /EventSetup/Format/BiiP3/catalogs/0/types/11/active = 0
List of values for Slots
To specify a slot which contains a list of values, you have to define the slot like this:
…/slots/[]<slotname> = [<separators>]<value>
For example
/EventSetup/Format/BiiP3/slots/[]p_args = [\t]%{EVENT_ARGS}
The [] modifier for the slotname provides the indication that this slot should be formatted as a “LIST of”.
The characters listed in the square brackets of the value indicate the separators. You should use
escaped characters like \t, \n etc …
The remainder of the value indicates the string which will be tokenized using the separators.
Definition of slots can be set at various levels as shown in the examples below.
/EventSetup/Format/<FORMAT>/slots/<SLOTNAME> = <SLOTVALUE>
/EventSetup/Format/<FORMAT>/catalogs/<CATALOG>/slots/<SLOTNAME> = <SLOTVALUE>
/EventSetup/Format/<FORMAT>/catalogs/<CATALOG>/types/<TYPE>/slots/<SLOTNAME> =
<SLOTVALUE>
Furthermore, the following special variables are defined.
/EventSetup/Format/<FORMAT>/active = 0|1
/EventSetup/Format/<FORMAT>/class = <BEM EV CLASSNAME>
/EventSetup/Format/<FORMAT>/catalogs/<CATALOG>/active = 0|1
/EventSetup/Format/<FORMAT>/catalogs/<CATALOG>/class = <BEM EV CLASSNAME>
/EventSetup/Format/<FORMAT>/catalogs/<CATALOG>/types/<TYPE>/class = <BEM EV CLASSNAME>
Forwarding events to the BPPM Event Management Cell
Events must be defined as active as discussed above before they will be forwarded to an event
management cell.
The agent leverages the cell API. The target cell configuration is defined in the following variables.
/EventSetup/Configuration/Key = <mcell key>
/EventSetup/Configuration/Primary = Host[/Port]
/EventSetup/Configuration/Secondary = Host[/Port]
All three variables are optional.
If Key is not specified, it will default to “mc”.
If only one of Primary or Secondary is specified, it will be used as the connection target host. If neither
as specified, a connection to “localhost” will be attempted
If port is not specified, the default port 1828 will be used.
The agent will persist events, regardless of the target host definition. This means, once a valid format is
specified, persistency will be in effect (unless the Primary or Secondary contains an invalid format).
Event Persistency / Guaranteed delivery
The guaranteed delivery and persistent storage of the events is provided by the cell API.
I18N
This feature is I18N enabled.
All data from the PATROL agent will be translated to UTF-8 prior to sending it via the API to the event
management cells.
Deployment options
With this feature, the agent becomes a BPPM event management cell client, much like msend or
mposter. Deployment options are therefore similar to that of any event management cell client.
The agent could connect to a cell local to the host on which the agent is running. The agent could also
connect to a cell installed on a remote machine. Finally, the agent can connect to an HA cell, where two
cells form a HA cluster.
Agent Interface Diagnostics
Debug can be enabled though the PEMTRACE debug function. To enable this start the PATROL Agent
with flags –debug PEMTRACE. Additionally, instance status information can be retrieved using %DUMP
BEMINFO in the PATROL Console system output window.
Macro variables
%{AGENT_VERSION}
- PATROL agent version (e.g., V3.5.00)
%{ALARM_MIN}
- Lower threshold of current alarm range (e.g., 90)
%{ALARM_MAX}
- Upper threshold of current alarm range (e.g., 100)
%{APPCLASS}
- Application Class Name (e.g., ORACLE)
%{APPINSTANCE}
- Instance Name (e.g., PROD1)
%{AVE10}
- Average of last 10 Parameter Values (e.g., 3.00)
%{DATE}
- Date of alert (MM/DD/YYYY)
%{EVENT_CATALOG}
- Event catalog name of originating event (e.g., 0)
%{EVENT_CLASS}
- Event class name of originating event (e.g., 11)
%{EVENT_ID}
- Event Manager's Event Id for the alert (e.g., 8765)
%{EVENT_SEVERITY}
- Event severity of originating event (e.g., 4)
%{EVENT_STATUS}
- Event Manager's Event Status for the alert (e.g., ESCALATED)
%{EVENT_TYPE}
- Event Manager's Event Type for the alert (e.g., ALARM)
%{HOSTNAME}
- Hostname (e.g., glamis)
%{ICON_NAME}
- Instance Icon Name (e.g., PROD1)
%{IPADDRESS}
- IP Address (e.g., 192.168.1.1)
%{LAST10}
- Last 10 Parameter Values (e.g., 1.00 2.00 3.00 4.00 5.00 etc.)
%{LAST10TP}
- Overall Time Period, in minutes, of LAST10 (e.g., 50.00)
%{LAST10TS}
- Last 10 Parameter Timestamps (e.g., 957359389 957359395
957359399 etc.)
%{OS_TYPE}
- Operating System type (e.g., NT 5.0 Service Pack 1)
%{PARAMETER_NAME}
- Parameter Name (e.g., CPUBusy)
%{PARAMETER_STATUS} - Parameter Status (e.g., ALARM,WARN,OK)
%{PARAMETER_VALUE} - Parameter Value (e.g., 99.65)
%{PARENT_INSTANCE} - Parent Instance Name (e.g., /ORACLE/ORACLE)
%{TCP_PORT}
- Agent's TCP listening port (e.g., 3181)
%{TIME}
- Time of alert (HH:MM:SS)
%{TIMEZONE}
- Time Zone on affected System (e.g., 'US/Eastern/EDT')
%{UDP_PORT}
- Agent's UDP listening port (e.g., 3181)
%{USERDEFINED}
- Value of variable
'/_my_%APPCLASS%_%APPINSTANCE%_%PARAMETER_NAME%'
Macro variables required for providing BiiP3 events
%{EVENT_ARGS}
%{EVENT_DESC}
%{EVENT_DIARY}
%{EVENT_EXPECTANCY}
%{EVENT_ORIGIN}
%{EVENT_OWNER}