Oracle
Enterprise Manager Administrator's Guide
Release 2.1 A75683-01 |
|
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:
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 adaptor should respond to and the operating system command it should execute in response to that event.
There are two ways to start the Event Handler: As a Management Server service, or as a client application.
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 (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.
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:
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.
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.
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:
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 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.
There are 2 ways to start the Event Handler
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. |
You need to supply a valid Management Server administrator and password in order to start the Event Handler.
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
For UNIX and Windows NT, enter the following at the command
line:
For Windows NT, you can start and stop the Management Server as a Service in the Control Panel (OracleORANTManagementServer).
Use the oemctrl utility to start the Event Handler.
oemctrl start eventhandler <oms-user> <oms-password> <nodename>
<oms-user> is a valid Management Server administrator
<oms-password> is the corresponding password
<nodename> is the node where the Management Server is running.
There are 2 ways to stop the Event Handler, each method corresponding to how it was started.
oemctrl stop oms <oms-user>/<oms-password>
/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
Example:
/com/oracle/sysman/em/eventHandler/global_filters/allEvents/eventname=*
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.
tracing_enabled = true logging_enabled = true Trace information will be generated to the log 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
/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
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.
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.
/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.
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 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
|
Copyright © 2000 Oracle Corporation. All Rights Reserved. |
|