|Oracle Enterprise Manager Administrator's Guide
Part Number A85248-01
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:
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.
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.
To set up and implement an Event Handler, you must perform the following steps:
Filters determine which events are passed on to the Event Logger and Command Executor adapters.
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.
Each of these steps are discussed in detail later in this appendix.
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.
Actual filter entries are defined in the omsconfig.properties file. The syntax for filters are as follows:
Syntax for global filters:
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:
Example: For the global_filter MyFilter:
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.
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.
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 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:
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>
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:
The name of the event.
The severity of the event as a string. (Alert, Clear, Warning, Node Down)
The timestamp of the event occurrence. (MM-dd-yyyy hh:mm:ss Example: 05-22-00 05:22:00 AM
Name of the target.
Type of the target. (oracle_sysman_node, oracle_sysman_database, oracle_sysman_listener)
The occurrence number of the event.
The assignee for this event.
The node on which the event occurred, not to be confused with target.
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:
To specify the message format that the template should use, the following format must be used:
An example of a template entry in the omsconfig.properties file would be:
/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 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.
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:
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 is the executable command, and
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:
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
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.
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.
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.
/com/oracle/sysman/em/eventHandler/handlers/eventlogger/entrypoint=oracle.sy sman.vda.vdae.VdaeEventLogger /com/oracle/sysman/em/eventHandler/handlers/eventlogger/processOnStartup=tru e
/com/oracle/sysman/em/eventHandler/handlers/commandexecutor/entrypoint=oracl e.sysman.vda.vdae.VdaeCommandExecutor /com/oracle/sysman/em/eventHandler/handlers/commandexecutor/processOnStartup =true
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.
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.
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 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
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.
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).
The Event Handler stops when the Management Server is stopped. Use the OEMCTRL utility to stop the Management Server.
Or, on machines running Windows NT, you can stop the Management Server by stopping the corresponding service (from Control Panel Services).
/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
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:
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
The following are useful filters and templates. Some of these entries can be found in the %ORACLE_HOME%/sysman/admin/omsconfig.properties.EventHandler file.
Pass all events to both event logger and command executor
Pass all events to the event logger
Pass all events to the command executor
Pass on all events except "cputest" to both event logger and command executor
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:
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:
/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.
Here, whenever any event fires, a telnet session is opened.
but do not specify the message format to use, for example:
You may see a NullPointerException.
For Event Handler entries that require a directory path, use the syntax that is appropriate to the operating system. For example