7
Event Handler

Enterprise IT practices may require that responses to certain event occurrences be handled in certain ways. For example, if the database updown event triggers, administrators may want to automatically open an in-house trouble-ticket so that the appropriate IT staff can respond to this event occurrence. The ability to provide customized automatic responses to event occurrences can be achieved by using the Event Handler. This chapter discusses the following topics:

Event Handler Overview

The Event Handler is an integral part of the Oracle Management Server. It listens for event notifications and responds to these events in ways specified by the administrator. The Event Handler's response capability is performed by its two components:

Event Logger - allows the Event Handler to log events to designated log files
Command Executor - allows simple operating system commands to be executed in response to an event occurrence.

You can use either or both components in response to a triggered event.

Prior to passing event notifications for further processing, the Event Handler also provides a simple filtering mechanism that allows system administrators to specify the conditions by which the events are passed to either or both components.

Figure 7-1 Event Handler Architecture

Text description of event_ha.gif follows.

Text description of the illustration event_ha.gif

How the Event Handler Works

When the Event Handler starts, information from the filters are used to determine which events the Event Handler should select and pass on to the Event Logger and/or Command Executor. Once these components receive the event, they further process the event based on the templates set up for the them. Templates provide a way to customize the behavior of the components. For the Event Logger, this means specifying which events should be logged and the specific log file to be used. For the Command Executor, this means specifying the types of events it should respond to and the operating system command it should execute in response to that event.

Figure 7-2 Event Handler Process

Text description of ch_handa.gif follows

Text description of the illustration ch_handa.gif

Setting Up the Event Handler

By default, the Event Handler has been pre-configured with default parameters and can be enabled immediately after installing Enterprise Manager. The default configuration implements the Event Logger only. To enable the Command Executor and/or customize the Event Handler's filtering capability, you will need to customize the Event Handler configuration. The two methods are outlined below.

Quickstart Method (Default)

Before enabling the Event Handler, the Management Server must first be stopped. To stop the Management Server, issue the following command:
```
% oemctl stop oms  <superuser>/<password>
```
Enable the Event Handler by typing the following:
```
% oemctl enable eventhandler
```
Start the Event Handler by starting the Management Server
```
% oemctl start oms
```

To view the default configuration of the Event Handler type the following:

% oemctl dump eventhandler

The Event Handler is now ready to use. This default configuration will log all events to a file called eventhandler.log, which is located in the %ORACLE_HOME/sysman/log directory. By default, the format of an Event Logger message is:

<name>;<occurrence number>;<timestamp>;<assignee, if any>;<severity>

and is overwritten each time the Event Handler starts.

The format and behavior of the default log message can be modified slightly by using the following properties in the omsconfig.properties file.

/com/oracle/sysman/em/eventlogger/logfile=<full logfile path> 
/com/oracle/sysman/em/eventlogger/separatorstring=<separator string for logfile entries>

/com/oracle/sysman/em/eventlogger/appendonstart=<true/false>

The separatorstring property is used by the default Event Logger template ONLY and cannot be used with user-defined Event Logger templates. This string separates placeholder entries within a single event occurrence, not different occurences of the event.

The appendonstart property determines whether or not the log file will be overwritten each time the Event Handler starts. The default is false, which means overwrite. Set this to true if new log entries should be appended to an existing log file.

Customizing the Event Handler Setup

To change the default configuration, you can customize the Event Handler as described in this section.

Before enabling the Event Handler, check to make sure the Management Server is not running. To stop the Management Server, issue the following command:
```
% oemctl stop oms  <superuser>/<password>
```
Enable the Event Handler by typing the following.
```
% oemctl enable eventhandler
```
Configure the Event Handler parameters.

The Event Handler parameters are stored in the Enterprise Manager repository. In order to change the parameter settings, you must export the parameters to a file, change the parameters, then import them back into the repository. These steps are illustrated below.

Note:
Make sure the Event Handler is first enabled as explained in step 2.

.

Export parameters to a text file

At the command line enter the following:
```
% oemctl export eventhandler <filename>
```
Example: % oemctl export eventhandler myEventHandler

This example exports the parameters to a text file called myEventHandler.

Change the parameters

Use any text editor to edit the contents of the file containing the exported parameters.

Details on the parameters are explained in "Event Handler Configuration Parameters" on page 7-7. It is important to follow the exact syntax for the parameters.

Import the parameters

Once you complete the parameter changes, they must be imported back to the repository. At the command line enter the following:
```
% oemctl import eventhandler <filename>
```
Example: % oemctl import eventhandler myEventHandler

This example imports the Event Handler settings defined in the file myEventHandler back into the Enterprise Manager repository.

Important:

Importing the parameter file will completely override any previous Event Handler settings.

Start the Management Server.

Starting the Management Server will start the Event Handler with the new settings.

% oemctl start oms

Event Handler Configuration Parameters

The Event Handler parameters are single-line entries that specify the events to which the Event Handler should respond and actions to be taken in response to these events.

Important:

The syntax for each entry should be followed exactly. There must be NO linefeed or carriage returns within a single entry.

Event Handler parameters fall into three categories: Blackouts, Filters, and Templates.

Blackouts

Syntax:

eventhandler.respect_blackouts = <true/false>

The blackouts parameter tells the Event Handler whether or not to act on an event if the event triggered on a target that has paging and email blackouts set. This parameter can be toggled true or false.

A setting of False (default setting) instructs the Event Handler to continue processing events even if paging and/or email blackouts have been set for those events.

A setting of True prevents the Event Handler from processing events on targets that have paging/email blackouts.

Filters

When the Event Handler starts, it uses "filters" to determine which events are passed on to the Event Logger and/or Command Executor components. The system administrator can designate what events, if any, are sent to the Event Logger and Command Executor components. This is called "filtering." Events may be filtered on a global basis (applied to both components) or on a per component basis. Filters apply to either the Event Logger or the Command Executor. Filters are defined in external files and imported into the Management Server by using the oemctl import eventhandler command. Each entry specifies the conditions by which the events are passed to the components. An event passes through the filter if it meets the conditions specified by the filter. Events that don't satisfy the condition are ignored by the Event Handler.

Each filter is uniquely identified by a name. All entries relating to a filter are grouped under this name. The filter conditions themselves are based on the following event properties:

Event properties for filters:

eventname -- this is the name of the event
node - this is the monitored node on which the event occurred
targetname - name of the target
targettype - type of the target. It is one of the following values:

oracle_sysman_node (target is a node)

oracle_sysman_database ( target is a database)

oracle_sysman_listener (target is a net listener)

oracle_sysman_cmanager (target is a concurrent manager)

oracle_sysman_ops (target is an ops node)

oracle_sysman_webserver (target is an apache webserver)

oracle_sysman_hotstandy (target is a standby database)
owner - owner of the event
severity - status of the event. It is one of the following values: alert, warning, error, clear, nodedown

Filter Syntax

The syntax for filters is as follows:

Syntax for global filters:

/com/oracle/sysman/em/eventHandler/global_filters/<filter-name>/<property-name> = <value>

Example:

/com/oracle/sysman/em/eventHandler/global_filters/myFilter/node = dlsun1234

Syntax for filters for the Event Logger only:

/com/oracle/sysman/em/eventHandler/eventlogger_filters/<filter-name>/<property-name> = <value>

Example:

/com/oracle/sysman/em/eventHandler/eventlogger_filters/myFilter2/owner = mary

Syntax for filters for the Command Executor only:

/com/oracle/sysman/em/eventHandler/commandexecutor_filters/<filter-name>/<property-name> = <value>

Example:

/com/oracle/sysman/em/eventHandler/commandexecutor_filters/myFilter3/severity = alert

Important:

The 'value' specified must either be an exact match or a single wildcard character "*" to specify all possible values. Regular expressions are not supported. For example, 'myevent*' is not an acceptable value. The sense of the condition can be negated by prefixing a "!" in front of the value.

The following rules apply to all event filters:

All conditions specified by a given filter must hold true for the event.

Example: For the global_filter MyFilter:

/com/oracle/sysman/em/eventHandler/global_filters/MyFilter/eventname = cputest
/com/oracle/sysman/em/eventHandler/global_filters/MyFilter/node = prodserver.us.oracle.com

If the name of the event is 'cputest' and if it occurred on node 'prodserver.us.oracle.com', then the event will be passed to both Event Handler components.

The event must pass at least one filter.
An event is forwarded to a component (Event Logger or Command Executor) if it passes through either a global filter or a filter for that particular component.

By default, all events are suppressed, and at least one filter (global or per component) must be present in order for events to be forwarded to any of the adapters. See Sample Filters and Templates: for examples of filters.

Assuming the event has passed through the filters, they are forwarded on to the event adapters, Event Logger or Command Executor.

Important:

The default Event Handler configuration provides a global filter that allows all events to be passed to both components: Event Logger and Command Executor. In most cases, this should be sufficient. Further selection of the type of events to respond to can be specified via templates which are discussed in the next section.

Templates

Templates tell the Event Logger and Command Executor adapters how to respond to the event occurrence. For the Event Logger, a template specifies which events should be logged and how this information should be formatted and to which file the information should be logged. For the Command Executor, a template specify the events the adapter should respond to and the operating system command it should execute in response to that event.

Event Logger Templates

The Event Logger logs events that have passed through the event filters (as discussed in the previous section). You specify how the event information is logged via templates.

Templates are configuration entries that tell the Event Logger: the events to which the templates apply, the log file to use, and the format by which the event information should be written.

You can have multiple templates defined. Each template must be uniquely identified by name. Each template should specify the following:

The events to which the template applies

Use this format:

/com/oracle/sysman/em/eventlogger/templates/<template-name>/<property-name> = <value>

where:

<template-name> is your name for this template
<property-name> is the property of the event used to determine the events to which this template applies
<value> is the value associated with the <property-name>

You can use any of the following event properties:

eventname : name of the event
node : the node on which the event triggered
targetname: name of the target
targettype: type of target

oracle_sysman_node (target is a node)

oracle_sysman_database ( target is a database)

oracle_sysman_listener (target is a net listener)

oracle_sysman_cmanager (target is a concurrent manager)

oracle_sysman_ops (target is an ops node)

oracle_sysman_webserver (target is an apache webserver)

oracle_sysman_hotstandy (target is a standby database)
owner: owner of the event
severity: status of the event. Can be any one of the following: alert, error, warning, clear, nodedown

To specify more than one event property, use multiple entries.

The following example specifies the template "MyTemplate" should be used when an event is triggered on node dlsun1234 AND the event severity is alert:

/com/oracle/sysman/em/eventlogger/templates/MyTemplate/node = dlsun1234
/com/oracle/sysman/em/eventlogger/templates/MyTemplate/severity = alert

If, in a single template, you would like to use the SAME event property multiple times in a logical AND relationship, you need to append a number to the event property name such that they're unique.

For example:

/com/oracle/sysman/em/eventlogger/templates/HRTemplate/eventname1=!spaceEvent
/com/oracle/sysman/em/eventlogger/templates/HRTemplate/eventname2=!cpuEvent
/com/oracle/sysman/em/eventlogger/templates/HRTemplate/message=Event %eventname% triggered on node %node% and 
has severity %severity%
/com/oracle/sysman/em/eventlogger/templates/HRTemplate/logfile=%ORACLE_HOME%/sysman/log/eventhandler.log

In the above example, the Event Logger will log a message of the specified format to a log file if the eventname is neither 'spaceEvent' nor 'cpuEvent'. This condition is expressed as "eventname is not spaceEvent" AND "eventname is not cpuEvent". Note the addition of numbers to the eventname property (eventname1 and eventname2) as a way to uniquely identify the same property within the template HRTemplate.

To specify more than one property in a disjointed relationship (OR, for example), use separate templates as illustrated in the next example.

This example specifies "MyTemplate1" should be used if the event triggered on node dlsun1234, OR if the event triggered on target orcl817, use "MyTemplate2".

/com/oracle/sysman/em/eventlogger/templates/MyTemplate1/node = dlsun1234

...

/com/oracle/sysman/em/eventlogger/templates/MyTemplate2/targetname = orcl817

...

Format for Event Information

You must also specify the message format to use when logging the event information to a log file. The formatting string used can contain placeholders, which are symbolic representations for pertinent pieces of information about the event. Placeholders are enclosed within "%" characters to distinguish them from ordinary words in the template string. Available placeholders are:

Table 7-1 Event Handler Place Holders

Place Holder	Definition
%eventname%	The name of the event.
%severity%	The severity of the event as a string. (Alert, Clear, Warning, Node Down)
%timestamp%	The timestamp of the event occurrence. (MM-dd-yyyy hh:mm:ss Example: 05-22-01 05:22:00 AM
%targetname%	Name of the target.
%targettype%	Type of the target. (oracle_sysman_node, oracle_sysman_database, oracle_sysman_listener)
%occ_no%	The occurrence number of the event.
%assignee%	The assignee for this event.
%node%	The node on which the event occurred, not to be confused with target.
%output%	The output associated with the event occurrence.
%owner%	The owner of the event.

To specify the message format that the template should use, the following format should be used:

/com/oracle/sysman/em/eventlogger/templates/<template-name>/message = <message format>

Example:

/com/oracle/sysman/em/eventlogger/templates/MyTemplate/message = %eventname% was triggered on %node% at 
severity %severity%

This example generates a logged message of the form:

TablespaceUsage was triggered on dlsun1234 at severity warning

Log file

Each template must specify the log file to which it will write:

/com/oracle/sysman/em/eventlogger/templates/<template-name>/logfile=<logfilename>

Example:

/com/oracle/sysman/em/eventlogger/templates/MyTemplate/logfile = /u1/myhome/myevents.log

An optional property can be specified to indicate whether or not the logfile should be appended or overwritten for each session that the Event Handler starts:

/com/oracle/sysman/em/eventlogger/templates/<template-name>/appendonstart = <true/false>

The default value is false, meaning each time the Event Handler starts, any old logfile entries will be overwritten by new log entries.

Note:

Forward slashes ("/") should always be used when specifying a path to ensure compatibility with both UNIX and Windows systems.

Multiple Event Logger Templates

In cases where the conditions of more than one template are met, all matching templates will be executed. Since each template has its own log file, it is possible to log events to multiple log files on one event notification.

An example of an entry in a template file would be:

/com/oracle/sysman/em/eventlogger/templates/foo/eventname=cputest

/com/oracle/sysman/em/eventlogger/templates/foo/message=%eventname% fired on %node%: Cpu usage on 
%targetname% is high! occ_no: %occ_no% Severity: %severity% Time: %timestamp%

/com/oracle/sysman/em/eventlogger/templates/foo/logfile=%ORACLEHOME%/sysman/log/ev.log

/com/oracle/sysman/em/eventlogger/templates/foo/appendonstart=true

The template definition above assigns all events named cputest to the template named foo. The optional appendonstart entry has also been specified. Whenever a cputest event fires, the logged output will appear in the file %ORACLE_HOME%/sysman/log/ev.log as follows:

cputest fired on smptest16: Cpu usage on smptest16 is high! occ_no: 21 Severity: Alert Time: 
10-21-2001 02:39:29 PM

The Command Executor Templates

The Command Executor executes simple commands in response to event occurrences. The Command Executor looks at a set of user-defined templates to decide what command to execute in response to event occurrences.

Templates are configuration entries that tell the Command Executor: the events to which the templates apply and the command to execute.

You can have multiple templates defined. Each template must be uniquely identified by name. Each template should specify the following:

The events to which the template applies

Use this format:

/com/oracle/sysman/em/commandexecutor/templates/<template-name>/<property-name> = <value>

where:

<template-name> is your name for this template
<property-name> is the property of the event used to determine the events to which this template applies, and
<value> is the value associated with the <property-name>

You can use any of the following event properties:

eventname : name of the event

node : the node on which the event triggered

targetname: name of the target

targettype: type of target

owner: owner of the event

severity: status of the event. Can be any one of the following: alert, error, warning, clear, nodedown

As in the Event Logger, to specify more than one event property, use multiple template entries.

Command to Execute

Use this format:

/com/oracle/sysman/em/commandexecutor/templates/<template-name>/command = <value>

where:

<value> is the command to execute

To include information about the event in the command, use placeholders. Placeholders are symbolic representations about pieces of information about the event. Placeholders are enclosed within "%" characters to distinguish them from ordinary words in the command string. For a list of available placeholders, see Table 7-1, "Event Handler Place Holders".

Optional: length of execution time

Optionally, you can also specify the length of time (in seconds) that the Event Handler will wait for a process to terminate after execution. For example, if a command begins a process that takes longer to run than what is normally acceptable, the Event Handler will automatically terminate the process.

Use this format to specify the execution time:

/com/oracle/sysman/em/commandexecutor/templates/<template-name>/exectimeout =<value>

where <value> is expressed in seconds.

By default, if the exectimeout parameter is not specified, the Event Handler will terminate the process after 40 seconds.

A typical entry for a template would be:

/com/oracle/sysman/em/commandexecutor/templates/foo/eventname=cputest

/com/oracle/sysman/em/commandexecutor/templates/foo/command=net send my-machine-name %eventname% 
fired on %node%: CPU usage on %targetname% is high! occ_no %occ_no% Severity: %severity% Time: 
%timestamp%

where "my-machine-name" is the name of the machine to which you want to send a message.

The template definition above assigns all events named cputest to the template named foo. Whenever a cputest event fires, the following message will be sent to machine "my-machine-name":

cputest fired on smptest16: Cpu usage on smptest16 is high! occ_no: 21 Severity: Alert Time: 
10-21-1999 02:39:29 PM

There may be situations where the command you want to execute has an argument consisting of several items, for example:

foo  a b c "this is a test"  "d=e"

where:

foo is the executable command, and

a is its first argument
b is its second argument
c is its third argument

this is a test is its fourth argument

d=e is its fifth argument.

In this case, you can use quotes ("") to group items within a single argument together as indicated in the example above, e.g. "this is a test". To include literal quotes as part of the argument, you need to prefix these quotes with backslashes (\). For example:

foo a b c  "d=\"e\""   "this is \"quoted\" "

will be pass the following arguments to foo:

a is the 1st argument

b is the 2nd argument

c is the 3rd argument

d="e" is the 4th argument

this is "quoted" is the 5th argument

Summary of Event Handler Configuration Commands

Typically, the way to configure the Event Handler would be to export the current configuration to a file, edit the file to change the entries, and then import the file back into the Enterprise Manager repository.

When a new Enterprise Manager repository is created, configuration entries are automatically created for all event notifications to be passed to the Event Handler, and for the Event Logger to log all event notifications into the file $ORACLE_HOME/sysman/log/eventhandler.log. However, the Event Handler is disabled by default.

The following is a summary of Event Handler Configuration Commands.

Enabling the Event Handler

To start the Event Handler, execute the following command:

oemctl enable eventhandler

Note: The Management Server must be stopped before executing this command.

Disabling the Event Handler

If at a subsequent time you need to disable the Event Handler, type

oemctl disable eventhandler

Viewing Current Event Handler Configuration Settings

To print out the current Event Handler configuration for viewing, type:

oemctl dump eventhandler

This will dump out the current Event Handler configuration to standard output. It will also indicate the Management Servers that are currently enabled with the Event Handler.

Creating a Configuration File from the Current Event Handler Configuration Registry Entries

To export the current Event Handler configuration registry entries into a file, type:

oemctl export eventhandler <filename>

You can then edit the configuration entries in the exported file. To import any changes, see the next section.

Importing a Configuration File

To import a file containing Event Handler configuration entries into the Enterprise Manager Repository, type:

oemctl import eventhandler <filename>

Importing the configuration file will completely override any previous Event Handler settings.

Important:

None of the Event Handler configuration commands take credentials since all Event Handler configuration commands inherit the repository credentials from the omsconfig.properties file. For this reason, before using the Event Handler configuration commands, you must first configure the Management Server.

Troubleshooting Tips

If the Event Logger and/or Command Executor do not seem to respond to events, check the following:

If the Command Executor does not run a specified shell script, perform the following:
- Specify the shell name or interpreter name before the command to execute the shell script as shown in the following example.
```
> /bin/sh  /db01/apps/oracle/eventresponse.sh
```
- Ensure the first line of the shell script invokes the shell or interpreter. In the example, this is /bin/sh. The first line of the shell script should be #!/bin/sh.
Make sure there are no linefeed characters within any single entry in the import file. The import utility will check for errors upon execution.
Make sure you have set a filter that allows events to pass through to them. This is part of the default configuration.
Example:
```
/com/oracle/sysman/em/eventHandler/global_filters/allEvents/eventname=*
```
Check the syntax of any templates associated with the Event Logger/Command Executor. Try using a simple template or any of the samples provided in this chapter.
When using the Event Logger on UNIX, make sure you have the appropriate permissions to create the log file. The Event Logger uses the permissions of the operating system user who started the Management Server. Try creating a file in the directory where the Event Logger's log file should have been created.
When using the Command Executor on UNIX, make sure you have the appropriate permissions to execute the command. The Command Executor uses the permissions of the operating system user who started the Management Server. Try running the command directly on the operating system to make sure it works.
Make sure the Event Handler service is available by typing the following command at the command prompt (You can also use this command at any time to check the current configuration of the Event Handler.):
```
>oemctl dump eventhandler
```
When using templates, make sure you specify both the event condition on which the template applies as well as the message format (for the Event Logger) or the command to be executed (for the Command Executor)
More advanced troubleshooting can be achieved by tracing the Event Handler. Because the Event Handler is an integral part of the Oracle Management Server, the Event Handler is automatically traced when you set up tracing for the Management Server. Trace information about the Event Handler will be included in the Management Server's trace/log file. Refer to Appendix B of the Oracle Enterprise Manager Configuration Guide for more information about Management Server tracing.

Note:

The Event Handler is an English-only release.

Sample Filters and Templates:

The following are sample filters and templates. Some of these entries can be found in the %ORACLE_HOME%/sysman/admin/EventHandler.examples file.

Filters:

Pass all events to both Event Logger and Command Executor

/com/oracle/sysman/em/eventHandler/global_filters/allNodes/node = *

Pass all events to the Event Logger

/com/oracle/sysman/em/eventHandler/eventlogger_filters/allEvents/eventname=*

Pass all events to the Command Executor

/com/oracle/sysman/em/eventHandler/commandexecutor_filters/allEvents/node=*

Pass on all events except "cputest" to both Event Logger and Command Executor

/com/oracle/sysman/em/eventHandler/global_filters/not-cputest/eventname = 
!cputest

Pass on all events named cputest that did not originate on the node smptest16 to the Event Logger:

/com/oracle/sysman/em/eventHandler/eventlogger_
filters/pass-some-cputest/eventname=cputest
/com/oracle/sysman/em/eventHandler/eventlogger_
filters/pass-some-cputest/node=!smptest16

Pass all events except cputest to the Command Executor adapter:

/com/oracle/sysman/em/eventHandler/commandexecutor_
filters/pass-no-cputest/eventname=!cputest

Pass on all events whose name is foo or whose originating node is skini-pc to the Command Executor:

/com/oracle/sysman/em/eventHandler/commandexecutor_filters/passfoo/eventname=foo
/com/oracle/sysman/em/eventHandler/commandexecutor_filters/pass-skini/node=skini-pc

Templates

Sample template for the Event Logger:

/com/oracle/sysman/em/eventlogger/templates/allEvents/eventname=*
/com/oracle/sysman/em/eventlogger/templates/allEvents/message=%eventname% fired 
on %node%:  Target %targetname%:  Output %output%  Severity: %severity%   Time: 
%timestamp%
/com/oracle/sysman/em/eventlogger/templates/allEvents/logfile=ev.log 
/com/oracle/sysman/em/eventlogger/templates/allEvents/appendonstart=false

A sample log entry using this template would look like:

cputest fired on smptest16:  Target smptest16:   Output Cpu usage is high.  
Severity: Alert  Time: 10-21-2001 02:39:29 PM

Sample templates for the Command Executor:

For Windows NT:

/com/oracle/sysman/em/commandexecutor/templates/allEvents2/eventname=*

/com/oracle/sysman/em/commandexecutor/templates/allEvents2/command=net send 
my-machine %eventname% fired on %node%: Target %targetname%: Output %output% 
Severity: %severity% Time: %timestamp%

where my-machine is the name of the PC to which the message will be sent.

Whenever any event fires, a message using the above format is sent to machine my-machine.

For UNIX:

/com/oracle/sysman/em/commandexecutor/templates/allEvents/command=xterm 
-display hqsun1:0 -e telnet

Here, whenever any event fires, a telnet session is opened.

Complex Example 1:

If the event name is foo or the originating node is prod-pc, log the string "Event %eventname% occurred on node %node%" into the file myevents.log. If the event name is anything other than foo, execute the command "mail admin@acme.com -s %eventname% %node%":

/com/oracle/sysman/em/eventlogger/templates/fooname/eventname=foo
/com/oracle/sysman/em/eventlogger/templates/fooname/message=Event %eventname% occurred on 
node %node%
/com/oracle/sysman/em/eventlogger/templates/fooname/logfile=myevents.log

/com/oracle/sysman/em/eventlogger/templates/prod/node=prod-pc
/com/oracle/sysman/em/eventlogger/templates/prod/message=Event %eventname% occurred on 
node %node%
/com/oracle/sysman/em/eventlogger/templates/prod/logfile=myevents.log

/com/oracle/sysman/em/commandexecutor/templates/anythingelse/eventname=!foo
/com/oracle/sysman/em/commandexecutor/templates/anythingelse/command=mail skini@oracle.com 
-s %eventname% %node%

Complex Example 2:

If the event severity is Alert, execute the commands "pager %eventname% dbapager" and "mail dba@acme.com -s %eventname% Highest Priority!!!" If the severity is anything else, only execute the command "mail dba@acme.com -s %eventname% Normal Priority"

/com/oracle/sysman/em/commandexecutor/templates/alertsev1/severity=alert
/com/oracle/sysman/em/commandexecutor/templates/alertsev1/command=pager %eventname% 
dbapager

/com/oracle/sysman/em/commandexecutor/templates/alertsev2/severity=alert
/com/oracle/sysman/em/commandexecutor/templates/alertsev2/command=mail dba@acme.com -s 
%eventname% Highest Priority!!!

/com/oracle/sysman/em/commandexecutor/templates/sevanythingelse/severity=!alert
/com/oracle/sysman/em/commandexecutor/templates/sevanythingelse/command=mail dba@acme.com 
-s %eventname% Normal Priority

Complex Example3:

If the eventname is neither 'spaceEvent' nor 'cpuEvent', then log a message of the format: "Event %eventname% triggered on node %node% and has severity %severity%" to a logfile called eventhandler.log in the directory %ORACLE_HOME%/sysman/log.

/com/oracle/sysman/em/eventlogger/templates/HRTemplate/eventname1=!spaceEvent
/com/oracle/sysman/em/eventlogger/templates/HRTemplate/eventname2=!cpuEvent
/com/oracle/sysman/em/eventlogger/templates/HRTemplate/message=Event %eventname% triggered 
on node %node% and has severity %severity%
/com/oracle/sysman/em/eventlogger/templates/HRTemplate/logfile=%ORACLE_
HOME%/sysman/log/eventhandler.log

Known Issues

The Event Handler may not start if there are any carriage return characters within any of the required entries. Some errors are caught by the import utility. If a problem with the file is encountered during import, an error message is displayed.

Differences between UNIX and Windows NT

For Event Handler entries that require a directory path, use the syntax that is appropriate to the operating system. For example

UNIX:

/com/oracle/sysman/em/eventlogger/logfile=/app/oracle/8.1.6/sysman/log/MyEvents.
log

Windows NT:

/com/oracle/sysman/em/eventlogger/logfile=c:\\orant\\sysman\\log\\MyEvents.log

Running the Event Handler in a multi-Management Server Environment

As part of the Management Server, the Event Handler has a high degree of reliability, failover, and load-balancing. However, certain rules apply when multiple Management Servers are connected to the same repository:

By default, the Event Handler is *not* enabled in a newly configured Management Server and must be explicitly enabled for each Management Server you set up, by using the oemctl enable eventhandler command. Conversely, to disable the Event Handler on one or more Management Servers, you must explicitly disable each Management Server by executing the oemctl disable eventhandler command.

Note:

The Management Server must be shut down when executing these commands.

If more than one Management Server is Event Handler enabled, then each event notification is handled exactly once and can be handled by any of the enabled Management Servers. There is no way to specify which of the enabled Management Servers should pick up an event notification. This means that the commands executed by the Command Executor must be available in the same way to all enabled Management Servers. Likewise, if you are using the Event Logger, the log file must be seen by all enabled Management Server's in exactly the same way, i.e., the same pathname. On Unix systems, for example, this could be achieved by using NFS file systems.
For situations where some Management Servers connected to a repository have the Event Handler disabled and others enabled, only Event Handler enabled Management Servers will pick up and execute Event Handler directives for event notifications (all Management Servers will continue to process event notifications in the usual way).

If one of the enabled Management Servers dies or is shut down, its Event Handler processing will failover automatically between the other enabled Management Servers. If all enabled Management Servers die (or are shut down) then Event Handler directives will not be processed by any of the remaining (Event Handler -disabled) Management Servers. In this situation, Event Handler operations will enter into the Management Server's reliability queue and will be processed as a batch once one or more of the Management Servers that were enabled for the Event Handler become operational.

Migrating from Prior Releases

If you used the Event Handler in Enterprise Manager 2.2 and wish to use the same configuration in Enterprise Manager 9i, then perform the following:

Copy all Event Handler entries from the omsconfig.properties file to a separate file. Use this separate file to make the changes described in the next steps.
If you're using the Event Logger

In Enterprise Manager 2.2, each template for the Event Logger shared the same log file. In Enterprise Manager 9i, each template has its own log file. To specify the logfile name, convert the template entry

From:
```
/com/oracle/sysman/em/eventlogger/logfile = <logfilename>
```
To:
```
/com/oracle/sysman/em/eventlogger/templates/<template-name>/logfile=<logfile
name>
```

Multiple templates can share the same logfile by specifying the same logfilename.
If you're using the Command Executor

No changes need to be done to the Command Executor templates.

Note:

In Enterprise Manager 2.x, if multiple templates match the event condition, only one of the templates will be used. In Enterprise Manager 9i, if multiple templates match the event condition, ALL templates will be used by both the Event Logger and Command Executor.

Enable the Event Handler

The Management Server must first be stopped before doing this step. Stop the Management Server by:

% oemctl stop oms <superadmin/password>

Then enable the Event Handler:

% oemctl enable eventhandler
Export the current settings

Export the Event Handler's current default configuration to another file.

% oemctl export eventhandler <config_filename>
Update the configuration file

Update the configuration file created in step 5 by replacing the default templates with the template settings you created in steps 2 and 3.
Import the configuration settings

% oemctl import eventhandler <config_filename>

where <config_filename> is the file in step 6 that has the updated Event Handler configuration entries.
Restart the Management Server to start the Event Handler

% oemctl start oms

You can verify the Event Handler settings by:

% oemctl dump eventhandler

7 Event Handler

Event Handler Overview

Figure 7-1 Event Handler Architecture

How the Event Handler Works

Figure 7-2 Event Handler Process

Setting Up the Event Handler

Quickstart Method (Default)

Customizing the Event Handler Setup

Event Handler Configuration Parameters

Blackouts

Syntax:

Filters

Filter Syntax

Templates

Event Logger Templates

Table 7-1 Event Handler Place Holders

Multiple Event Logger Templates

The Command Executor Templates

The events to which the template applies

Command to Execute

Optional: length of execution time

Summary of Event Handler Configuration Commands

Enabling the Event Handler

Disabling the Event Handler

Viewing Current Event Handler Configuration Settings

Creating a Configuration File from the Current Event Handler Configuration Registry Entries

Importing a Configuration File

Troubleshooting Tips

Sample Filters and Templates:

Filters:

Templates

Complex Example 1:

Complex Example 2:

Complex Example3:

Known Issues

Differences between UNIX and Windows NT

Running the Event Handler in a multi-Management Server Environment

Migrating from Prior Releases

7
Event Handler