event properties
Oracle Enterprise Manager Administrator's Guide Release 9.0.2 Part Number A95407-01 |
|
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:
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:
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.
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.
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.
% oemctl stop oms <superuser>/<password>
% oemctl enable eventhandler
% 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 logger template ONLY and cannot be used with user-defined 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.
To change the default configuration, you can customize the Event Handler as described in this section.
% oemctl stop oms <superuser>/<password>
% oemctl enable eventhandler
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.
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.
Starting the Management Server will start the Event Handler with the new settings.
% oemctl start oms
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.
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.
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:
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)
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
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 both Event Handler components.
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.
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.
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 appliesUse this format:
/com/oracle/sysman/em/eventlogger/templates/<template-name>/<property-name> = <value>
where:
You can use any of the following event properties:
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)
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 InformationYou 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:
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 warningLog 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. |
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 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:
Use this format:
/com/oracle/sysman/em/commandexecutor/templates/<template-name>/<property-name> = <value>
where:
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.
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".
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
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
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.
To start the Event Handler, execute the following command:
oemctl enable eventhandler
Note: The Management Server must be stopped before executing this command.
If at a subsequent time you need to disable the Event Handler, type
oemctl disable eventhandler
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.
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.
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.
Example:
/com/oracle/sysman/em/eventHandler/global_filters/allEvents/eventname=*
>oemctl dump eventhandler
You can use this command at any time to check the current configuration of the Event Handler.
The following are sample filters and templates. Some of these entries can be found in the %ORACLE_HOME%/sysman/admin/EventHandler.examples 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 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
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:
/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.
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%
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
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
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
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:
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.
If you used the Event Handler in Enterprise Manager 2.2 and wish to use the same configuration in Enterprise Manager 9i, then do the following:
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.
No changes need to be done to the command executor templates.
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 Event Handler's current default configuration to another file.
% oemctl export eventhandler <config_filename>
Update the configuration file created in step 5 by replacing the default templates with the template settings you created in steps 2 and 3.
% oemctl import eventhandler <config_filename>
where <config_filename> is the file in step 6 that has the updated Event Handler configuration entries.
% oemctl start oms
You can verify the Event Handler settings by:
% oemctl dump eventhandler
|
Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|