A
Enterprise Manager Event Handler

Important:
The Event Handler is a pre-production feature in this release of Enterprise Manager and should not be used in a production environment.

Applications accessing the Oracle Management Server event services may require trapping of specific event conditions and the ability to handle them appropriately. This can be achieved using the Event Handler, an application that listens for event notifications from the Oracle Management Server and allows these events to be further processed by event "adapters". An adapter is an additional piece of software that takes events from the Event Handler for further processing.

Enterprise Manager 2.1 ships with 2 event adapters:

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

These adapters permit other types of applications to integrate with the Enterprise Manager event system and trigger other operations based on these trapped events. You can have either or both adapters working with the Event Handler.

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 event adapters.

Figure A-1 Event Handler Architecture

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 adapters. Once the adapters receive the event, they further process the event based on the templates set up for the adapter. Templates provide a way to customize the behavior of the adapters. For the Event Logger, this means specifying which events should be logged. 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 A-2 Event Handler Process

How to Set Up the Event Handler

To set up and implement an Event Handler, you must perform the following steps:

Define the filters.

Filters determine which events are passed on to the Event Logger and Command Executor adapters.
Define the templates.

Templates tell the Event Logger and Command Executor adapters how to process the event. For the Event Logger, a template specifies which events should be logged and how the information should be formatted. For the Command Executor, a template specifies the events the adaptor should respond to and the operating system command it should execute in response to that event.
Determine how to start up the Event Handler

There are two ways to start the Event Handler: As a Management Server service, or as a client application.
Start up the Event Handler

Each of these steps are discussed in detail later in this appendix.

Defining Event Filters

When the Event Handler starts, it uses "filters" to determine which events are passed on to the Event Logger and/or Command Executor adapters. The system administrator can designate what events, if any, are sent to the Event Logger and Command Executor adapters. This is called "filtering." Events may be filtered on a global basis (i.e. applied to both adapters) or on a per-adapter basis. Filters are set up by means of entries in the omsconfig.properties file located in the $ORACLE_HOME/sysman/config directory. Each entry specifies the conditions by which the events are passed to the adapters. The conditions are based on 'eventname' and/or 'node' on which the event occurred. An event passes thru the filter if it meets the conditions specified by the filter.

Each filter is distinguished by having a common name associated with it and the entries for that filter are grouped under this common name.

Filter Syntax

Actual filter entries are defined in the omsconfig.properties file. The syntax for filters are as follows:

Syntax for global filters:

/com/oracle/sysman/em/eventHandler/global_filters/<filter-name>/<'eventname' or 
'node'> = <value>

Syntax for filters for the Event Logger only:

/com/oracle/sysman/em/eventHandler/eventlogger_
filters/<filter-name>/<'eventname' or 'node'> = <value>

Syntax for filters for the Command Executor only:

/com/oracle/sysman/em/eventHandler/commandexecutor_
filters/<filter-name>/<'eventname' or 'node'> = <value>

The character "*" can be used as a wildcard character to specify all possible values. 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 be 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 all event adapters.

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

By default, all events are suppressed, and at least one filter (global or adapter-specific) 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 thru the filters, they are forwarded on to the event adapters, Event Logger or Command Executor. We will describe what happens to them next.

Important:
Another level of filtering occurs when you start the Event Handler itself. In order to start the Event Handler, you need to provide a valid Management Server administrator and password. This Management Server administrator will have associated events that it will be able to receive. If you start the Event Handler using a particular Management Server administrator, then the Event Handler will only be able to receive event notifications to which that Management Server administrator has been given at least VIEW permissions. If you start the Event Handler using the sysman or superuser account, it will receive ALL events. Hence all events that the Management Server administrator is not entitled to receive will *not* be received by the Event Handler.

The Event Logger Templates

The Event Logger logs events received from the Management Server to a file.

The default log file is $ORACLE_HOME/sysman/log/event.log. 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, read as entries 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 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.

You can further customize Event Logger operation by using templates. Templates are strings that generically represent the format of a message as a way to customize the format of event notifications written to a log file. A template contains one or more place holders, which are symbolic representations for pertinent pieces of information about the event. Place holders are enclosed within "%" characters to distinguish them from ordinary words in the template string. Available place-holders are:

Table 8-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-00 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.

Templates are declared by making entries in the omsconfig.properties file. Events can be assigned to templates based on event names or originating node (the same criteria used by the Event Handler filtering system). Templates use this format to specify which events the template should apply:

/com/oracle/sysman/em/eventlogger/templates/<template-name>/<'event_name' or 
'node'>=<value>

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

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

An example of a template entry in the omsconfig.properties 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%

The template definition above assigns all events named cputest to the template named foo. Whenever a cputest event fires, the logged output will appear as follows:

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

Note: Templates override the default message format.

As with Event Handler filters, the wildcard character "*" can be used for event names and node names. If more than one template criterion matches an event occurrence, only one of them is randomly chosen. For this reason, care should be used when assigning events to templates.

The Command Executor Templates

The Command Executor adapter 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 an event occurrence. A template can contain several place-holders, which are symbolic representations for interesting pieces of information about the event. Place-holders are enclosed within '%' characters to distinguish them from ordinary words in the template string. For a list of currently used place-holders, see Table 8-1, "Event Handler Place Holders"

As with the Event Logger, templates are declared by making entries in the omsconfig.properties file. Events can be assigned to templates based on event names or originating node (the same criteria offered by the event-handler filtering system).

Templates use this format to specify the events to which the template should apply.

/com/oracle/sysman/em/eventlogger/templates/<template-name>/<'event_name' or 
'node'>=<value>

Templates use the following format to specify the command to which the template should apply:

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

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

As with event-handler filters, the character '*' can be used to wildcard event names and node names. If more than one template criterion matches an event occurrence, only one of them is randomly chosen. It is important, therefore, to be careful when assigning events to templates.

Starting up and Running the Event Handler

There are 2 ways to start the Event Handler

As a Management Server service
As a client application

In both cases, make sure you have the following entries in the omsconfig.properties file. This is located in the %ORACLE_HOME%\sysman\config directory. %ORACLE_HOME% refers to the Oracle Home directory where Enterprise Manager was installed.

Note:
For convenience, these entries are in the %ORACLE_HOME%/sysman/admin/omsconfig.properties.EventHandler file. Simply copy the entries from this file into the omsconfig.properties file.

The following configuration file entries relate to the Event Logger:

/com/oracle/sysman/em/eventHandler/handlers/eventlogger/entrypoint=oracle.sysman
.vda.vdae.VdaeEventLogger
/com/oracle/sysman/em/eventHandler/handlers/eventlogger/processOnStartup=true

The following configuration file entries relate to the Command Executor:

/com/oracle/sysman/em/eventHandler/handlers/commandexecutor/entrypoint=o
racle.sysman.vda.vdae.VdaeCommandExecutor
/com/oracle/sysman/em/eventHandler/handlers/commandexecutor/processOnSta
rtup=true

Important:
There should be NO carriage returns or linefeed characters within each entry. This is true for all entries in any of the Enterprise Manager configuration files.

Starting the Event Handler

You need to supply a valid Management Server administrator and password in order to start the Event Handler.

Start the Event Handler as a Management Server Service

Before you can start the Event Handler as a Management Server service, you must add the following entries to the OMSExternalRegistry.registry file (located in %ORACLE_HOME%/sysman/config), substituting the appropriate values for <oracle-home>, <OMS User>, <OMS password>, and <OMS nodename>:

/com/oracle/sysman/em/oms/services/external/EventHandlerSession/external_
service_name = EventHandlerSession
/com/oracle/sysman/em/oms/services/external/EventHandlerSession/name = 
EventHandlerSession
/com/oracle/sysman/em/oms/services/external/EventHandlerSession/oms_service_
interface = oracle.sysman.vda.vdae.VdaeEventHandlerSession
/com/oracle/sysman/em/oms/services/external/EventHandlerSession/startup_
mode=1
/com/oracle/sysman/em/oms/services/external/EventHandlerSession/name_value_
pair=ORACLE_HOME=<oracle-home>
/com/oracle/sysman/em/oms/services/external/EventHandlerSession/args=-s,<OMS 
User>,<OMS Password>,<OMS nodename>
/com/oracle/sysman/em/oms/services/external/EventHandlerSession/service_
classpath=
/com/oracle/sysman/em/oms/services/external/EventHandlerSession/outfile_
destination=<oracle-home>/sysman/log
/com/oracle/sysman/em/oms/services/external/EventHandlerSession/errfile_
destination=<oracle-home>/sysman/log
/com/oracle/sysman/em/oms/services/external/EventHandlerSession/logfile_
name=eventHandler

Note:
For convenience, these entries can be found in the %ORACLE_HOME%/sysman/admin/OMSExternalRegistry.registry.EventHandler file. Simply copy the entries from this file and paste them into the OMSExternalRegistry.registry file located in your %ORACLE_HOME%/sysman/config directory.

Start the Management Server.

For UNIX and Windows NT, enter the following at the command line:

oemctrl start oms

For Windows NT, you can start and stop the Management Server as a Service in the Control Panel (OracleORANTManagementServer).

Start the Event Handler as a client application

Use the oemctrl utility to start the Event Handler.

oemctrl start eventhandler <oms-user> <oms-password>  <nodename>

where:

<oms-user> is a valid Management Server administrator

<oms-password> is the corresponding password

<nodename> is the node where the Management Server is running.

Stopping the Event Handler

There are 2 ways to stop the Event Handler, each method corresponding to how it was started.

If the Event Handler was started as an Management Server service, then it will be stopped when the Management Server stops. Use the OEMCTRL utility to stop the Management Server.

oemctrl stop oms <oms-user>/<oms-password>
If the Event Handler was started as a client application using the oemctrl utility, then stop the utility using Ctrl-C.

Troubleshooting Tips

When starting the Event Handler as a client application, make sure that the Management Server is up and running when you do so.
If the logger/executor doesn't seem to respond to events, check the following:
1. Make sure you have the appropriate entries to start the logger and executor in the omsconfig.properties file. These are:
```
/com/oracle/sysman/em/eventHandler/handlers/eventlogger/entrypoint=oracl
e.sysman.vda.vdae.VdaeEventLogger
/com/oracle/sysman/em/eventHandler/handlers/eventlogger/processOnStartup
=true

/com/oracle/sysman/em/eventHandler/handlers/commandexecutor/entrypoint=o
racle.sysman.vda.vdae.VdaeCommandExecutor
/com/oracle/sysman/em/eventHandler/handlers/commandexecutor/processOnSta
rtup=true
```
2. Make sure the Management Server administrator used to start the Event Handler receives the event notification via the EM console. The Management Server administrator needs to have at least VIEW permissions on the event.
3. Make sure you have set a filter that allows events to pass through to them. Try initially setting a filter that allows *all* events to pass through.
  
  Example:
```
/com/oracle/sysman/em/eventHandler/global_filters/allEvents/eventname=*
```
4. Check the syntax of any templates associated with the logger/executor. Try using a simple template or any of the samples given below.
5. When using the logger on unix, make sure you have the appropriate permissions to create the log file. It will use the permissions of the operating system user who started the Event Handler. Try creating a file in the directory where the logger's log file should have been created.
6. When using the command executor on unix, make sure you have the appropriate permissions to execute the command. It will use the permissions of the operating system user who started the Event Handler. Try running the command directly on the operating system to make sure it works.
7. If you started the Event Handler as an Management Server service, make sure the service is still up. Check the screen where you started the Management Server and watch for messages that indicate the Event Handler is no longer running. If on a UNIX system, check to see if the service is running.
8. Make sure there are no linefeed characters within any single entry in the omsconfig.properties and OMSExternalRegistry.registry file.
9. 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)
The Event Handler is an English-only release.

Tracing

Should come as a last resort to find out errors that have occurred with the Event Handler. Trace information can be directed either to the screen or to a log file in the %ORACLE_HOME%\sysman\log directory. To enable logging or tracing, turn on the options specified in the omsconfig.properties file and restart the Event Handler.

/com/oracle/sysman/em/eventHandler/tracing_enabled = true or false
/com/oracle/sysman/em/eventHandler/logging_enabled = true or false

The trace information generated can either be generated to a file or to the screen. If tracing_enabled is set to true, then any trace information will be sent to the screen. If logging_enabled is set to true, then trace information will be generated in the log file. However, logging takes precedence, i.e. if logging_enabled is true, then trace information will always be sent to the log file.

These are the various combinations and their output:

tracing_enabled = false
logging_enabled = false
No trace on screen or in the log file.

tracing_enabled = false
logging_enabled = true
Trace information will be generated to the log file.

tracing_enabled = true
logging_enabled = false
Trace information will be generated to the screen.

Note:
If the Event Handler was started as an external service, then the trace will be written to the file specified by the logfile_name entry and in the directory specified by outfile_destination entry in the OMSExternalRegistry.registry file

tracing_enabled = true
logging_enabled = true
Trace information will be generated to the log file.

Sample Filters and Templates:

The following are useful filters and templates. Some of these entries can be found in the %ORACLE_HOME%/sysman/admin/omsconfig.properties.EventHandler 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 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

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%

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-1999 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 Solaris:

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

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

Known Issues

The Event Handler may not start if there are any carriage return characters within any of the required entries.
If you specify incomplete template entries, for example:
```
/com/oracle/sysman/em/eventlogger/templates/allEvents/eventname=* 
```
but do not specify the message format to use, for example:
```
/com/oracle/sysman/em/eventlogger/templates/allEvents/message= ...  
```
You may see a NullPointerException.
The default message format used by the Event Logger displays a numeric value indicating the severity. For example:

cputest;6;10-27-99 12:43:51 PM;;25

To obtain the actual severity level, define a message template and use the %severity% placeholder.
For slower machines, starting the Event Handler as an External service may generate an error message stating the Event Handler is no longer available. This is due to discrepancies in synchronization speed. Nothing is wrong with the Event Handler. Wait a few minutes to allow the Event Handler to initialize.

Differences between Solaris and Windows NT

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

Solaris:

/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

A Enterprise Manager Event Handler