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.2 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

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

1. Define the filters.

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

2. 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 adapter should respond to and the operating system command it should execute in response to that event.

3. Start up the Event Handler. For Enterprise Manager 2.2, the Event Handler starts up as one of the services of the Management Server.

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 (applied to both adapters) or on a per adapter basis. Filters apply to either the Event Logger or the Command Executor. 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 through 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:

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

2. The event must pass at least one filter

3. An event is forwarded to an adapter (Event Logger or Command Executor) if it passes through 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) 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. 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 6-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 6-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>

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

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

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

Starting up and Running the Event Handler

The Event Handler is one of the Management Server services. Hence, it is started or shut down when the Management Server is started or shut down.

1. Add the following entries to the omsconfig.properties file.

   To start the Event Handler, 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.sy
sman.vda.vdae.VdaeEventLogger
/com/oracle/sysman/em/eventHandler/handlers/eventlogger/processOnStartup=tru
e

The following configuration file entries relate to the Command Executor:

/com/oracle/sysman/em/eventHandler/handlers/commandexecutor/entrypoint=oracl
e.sysman.vda.vdae.VdaeCommandExecutor
/com/oracle/sysman/em/eventHandler/handlers/commandexecutor/processOnStartup
=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.

Add the Enterprise Manager Administrator to the omsconfig.properties file.

You need to start up the Event Handler using a valid set of Enterprise Manager credentials.

Specify the Enterprise Manager Administrator by adding the following entries to the omsconfig.properties file.

eventhandler.user=<EM administrator>
eventhandler.passwd=<corresponding password>

When the Event Handler is started for the first time, it reads the eventhandler.passwd entry, encrypts it, and writes it back in encrypted form as another entry, eventhandler.passwd.encr. The original non-encrypted password will be removed. Thereafter, it will use the encrypted password only.

If you need to change the password, remove the eventhandler.passwd.encr entry, and add the eventhandler.passwd again.

Add the appropriate entries to the OMSExternalRegistry.registry file.

Add the following entries to the OMSExternalRegistry.registry file (located in %ORACLE_HOME%/sysman/config), substituting the appropriate values for <oracle-home>:

/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
/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.

4. In the omsconfig.properties file, specify your filters and templates for the Event Logger and Command Executor as discussed in the previous sections.

5. 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).

Stopping the Event Handler

The Event Handler stops when the Management Server is stopped. Use the OEMCTRL utility to stop the Management Server.

oemctrl stop oms <oms-user>/<oms-password>

Or, on machines running Windows NT, you can stop the Management Server by stopping the corresponding service (from Control Panel Services).

Troubleshooting Tips

• 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. Make sure the Event Handler 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.

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 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

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.

• If there is a problem starting the Event Logger, as indicated previously, this problem may affect the Command Executor also. The reverse is also true: if there is a problem starting the Command Executor due to incorrect configuration entries, then it may affect the operation of the Logger. Set up Event Handler tracing to determine the root problem.

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