This chapter describes how to create alerts to notify you when a certain condition exists. Optionally, these alerts can be delivered by email, command line interface, or Simple Network Management Protocol (SNMP).
This chapter includes the following sections:
Oracle GoldenGate Monitor alerts notify you when a specified condition exists for an Oracle GoldenGate component. For example, you can request notification when a process stops or when a specified lag threshold is reached. You select the information to include in the message. To define alerts go to Alert Definitions in the user interface and follow the instructions in the online help.
Each user specifies which types of alerts Oracle GoldenGate Monitor should produce for them. To enable alerts for a user, go to the User Profile in the Oracle GoldenGate Monitor user interface and follow the instructions in the online help.
You can configure Oracle GoldenGate Monitor alerts to be delivered to e-mail accounts.
To use this feature you must:
Enable e-mail alerts by checking the SMTP (Simple Mail Transfer Protocol) alerts box during installation or later setting the e-mail alerts properties in the monitor.properties
file as explained in the next section.
Enter the user's e-mail address in the User Management tab of the Oracle GoldenGate Monitor user interface.
Go to the User Profile in the Oracle GoldenGate Monitor user interface and select e-mail as the notification type for the appropriate severity level.
If you did not set up e-mail alerts during the installation, you can do so by setting the following properties in the monitor.properties
file:
Enable e-mail alerts by setting the following property to true
:
monitor.smtp.alerts.enabled=true
Specify the name of the sender for Oracle GoldenGate Monitor communications generated from the e-mail server.
monitor.smtp.from=sender_name
Specify the host name of the e-mail server.
monitor.smtp.host=email_host_name
Specify the port that the e-mail server uses.
monitor.smtp.port=port_number
Specify whether the e-mail server is in secure mode.
monitor.smtp.secure={true | false}
If the e-mail server is in secure mode, specify the user authorized to log in.
monitor.smtp.user=user_name
If the e-mail server is running in secure mode, to change your password, you must log in to the WebLogic Scripting Tool (WLST) and use the createCred()
command; for example:
wls:/test_domain/serverConfig>createCred(map="OGGMONITOR",key="WEB.SMTP.EMAIL.PASSWORD",user="<email user id>",password="<email password>",desc="SMTP EMAIL Password")
For more information on using WLST, see Understanding the WebLogic Scripting Tool.
The Oracle GoldenGate Monitor Command-Line Integration (CLI) allows you to run a script or object file on the Oracle GoldenGate Monitor Server when an alert is triggered.
To use this feature you must enable CLI alerts by checking the CLI alerts box during installation or later setting the monitor.cli.alerts.enabled
property equal to true
in the monitor.properties
file.
The Oracle GoldenGate Monitor installation delivers files to help you configure your CLI interface. These are delivered to the cfg
subdirectory of the installation location.
CommandLineHandlers.xml
The CLI interface is configured in the CommandLineHandlers.xml
file.
Two example CommandLineHandlers.xml
files, one for UNIX and one for Windows, are included with the installation. Each contains sample syntax for configuring a CLI interface. You can copy the appropriate version and then add and change arguments to create the CommandLineHandlers.xml
that will configure your CLI interface.
This file contains the definition for the CommandLineHandlers.xml
file. It can be used to generate the CommandLineHandlers.xml
using a commercial or open source XML generation tool that creates sample XML from XSD.
After you configure the CommandLineHandlers.xml
, stop and restart the Oracle GoldenGate Monitor Server to activate the changes. See "Starting and Stopping Oracle GoldenGate Monitor Server" for directions on how to do this.
The example UNIX configuration below illustrates the structure and arguments of the XML configuration file. The header values should not be changed. These values specify the version and coding of the XML.
Arguments are specified by entering a value within quotation marks after the equal sign (=) as shown in the example. In this illustration namespace and schema information has been omitted as indicated by the ellipses (. . .
).
<?xml version="1.0" encoding="UTF-8"?> <CommandLineHandlers . . .> <CommandLineHandler dateTimeFormat="MMddyyyyHHmmssSSS" executeIn="/home/user" name="CMDLINE"> <externalCommand>touch</externalCommand> <arguments> <argument argText="filename" name="hostname" presentIfEmpty="true" quoted="false"/> </arguments> <alertMappings> <alertMapping alertField="host" name="hostname"/> </alertMappings> </CommandLineHandler> </CommandLineHandlers>s
CommandLineHandler
is the parent tag for the CLI alert handler. This is specified within the CommandLineHandlers
tags.
<CommandLineHandler dateTimeFormat="MMddyyyyHHmmssSSS" executeIn="/home/user" name="CMDLINE">
The CommandLineHandler
tag includes the following arguments:
This is the standard Java format argument described in Java documentation.
The executeIn
argument triggers the processing to move into the specified directory before running the external script or object file. The default is to use the current run directory of the virtual machine (VM); the directory in which the script or command was started.
A RunTimeException
is generated when the alert is triggered if the specified directory does not exist or if the executeIn
attribute is empty or not present.
name
This will always be "CMDLINE
".
The following example illustrates the tags that can be nested within the CommandLineHandler
tags:
<externalCommand>touch</externalCommand> <arguments> <argument argText="filename" name="hostname" presentIfEmpty="true" quoted="false"/> </arguments> <alertMappings> <alertMapping alertField="host" name="hostname"/> </alertMappings>
externalCommand
The value in externalCommand
specifies the absolute path to the script or object file. If the system path environment variable points to the directory of the file to be run, you can specify the script or object file name without the path.
arguments
The arguments
tag specifies one or more values that are appended to the directory value specified in the externalCommand
tag.
For each argument the following attributes can be specified:
argText
- Specifies a literal text argument that is sent with the externalCommand
tag.
name
- Can be a name or it can work with alertMappings
to find a name as explained below.
presentIfEmpty
- Works with the alertMappings
tag to add selected information associated with the alert definition to the externalCommand
tag. See alertMappings below for more detail.
alertMappings
The alertMappings
tag appends the value extracted from the alert definition information to the value specified in the externalCommand
tag.
<alertMappings> <alertMapping alertField="host" name="hostname"/> </alertMappings>
The alertField can be one of the following values associated with the alert definition:
alertName
- The name of an alert definition.
host
- The host of the Oracle GoldenGate object whose monitoring point triggers the alert.
alertObjectName
- The name associated with the object whose monitoring point triggers the alert, such as an Extract process named EXACCT.
alertTime
- The time that the alert was triggered.
alertSeverity
- The severity level defined for the alert; either Warning or Error.
alertMessage
- The message generated by the alert. This is a combination of the condition defined for the alert, the value of the monitoring point, and literal text.
changedValue
- The new monitoring point value that triggered the alert. For example, you create an alert that is triggered when lag is greater than 5 seconds. The lag is 4 seconds and then it goes to 7 seconds. This triggers the alert and the changedValue
is 7.
In the following example, the name
attributes in the argument
and the alertMapping
tags are matched to extract the value from the alertField
attribute. The argument
name
"hostname
" is matched to the alertMapping
name
"hostname
" to find the value of alertField
, which is "host
". This tells the system to append the host of the Oracle GoldenGate object that triggered the alert to the value specified in the externalCommand
tag.
<arguments> <argument argText="text" name="hostname" presentIfEmpty="true" quoted="false"/> </arguments> <alertMappings> <alertMapping alertField="host" name="hostname"/> </alertMappings>
The presentIfEmpty
attribute works with the alertMappings
tag to determine what to do if the alertField
is not valid or the name
attributes do not match:
presentIfEmpty="true"
The
value in the argText
attribute is used in the external command.
presentIfEmpty="false"
The entire argument is omitted.
These examples run a batch script on the Oracle GoldenGate Monitor Server.
The following example runs the batch script sample_cli.bat
on a Windows server hosting the Oracle GoldenGate Monitor Server. The server of the Oracle GoldenGate instance ("host
") that triggered the alert is appended to the name of the batch script specified in the externalCommand
.
<?xml version="1.0" encoding="UTF-8"?> <CommandLineHandlers xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.yourlocation/monitor/commandlinehandlers/CommandLineHandlers.xsd"> <CommandLineHandler dateTimeFormat="MMddyyyyHHmmssSSS" executeIn="C:\" name="CMDLINE"> <externalCommand>c:\sample_cli.bat</externalCommand> <arguments> <argument argText="" name="hostname" presentIfEmpty="true" quoted="false"/> </arguments> <alertMappings> <alertMapping alertField="host" name="hostname"/> </alertMappings> </CommandLineHandler> </CommandLineHandlers>
The following example runs the sample_cli.sh
script on the UNIX server hosting the Oracle GoldenGate Monitor Server. The server of the Oracle GoldenGate instance ("host
") that triggered the alert is appended to the name of the batch script specified in the externalCommand
.
<?xml version="1.0" encoding="UTF-8"?> <CommandLineHandlers xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.yourlocation/monitor/commandlinehandlers/CommandLineHandlers.xsd"> <CommandLineHandler dateTimeFormat="MMddyyyyHHmmssSSS" executeIn="/home/user" name="CMDLINE"> <externalCommand>bash</externalCommand> <arguments> <argument argText="/home/user/sample_cli.sh" name="hostname" presentIfEmpty="true" quoted="true"/> </arguments> <alertMappings> <alertMapping alertField="host" name="hostname"/> </alertMappings> </CommandLineHandler> </CommandLineHandlers>
The Oracle GoldenGate Monitor Simple Network Management Protocol (SNMP) interface sends alerts in the form of datagrams. These are picked up by an SNMP trap recipient listening on a specified port.
To use this feature you must enable SNMP alerts during installation or later set the monitor.snmp.alerts.enabled
property equal to true
in the monitor.properties
file.
The GoldenGate-Monitor-mib.mib
file is delivered to the cfg
subdirectory during the installation of Oracle GoldenGate Monitor. This contains the Management Information Base (MIB) definitions the target uses to interpret the alerts. If you need to interpret information received in the traps, import this file to the target tool.
The SNMP alert is configured in the SNMPJMXMapping.xml
file that is delivered to the cfg
subdirectory during the Oracle GoldenGate installation.
Any changes to the SNMPJMXMapping.xml
file must be made outside of the Oracle GoldenGate Monitor user interface by the host administrator that installed the Oracle GoldenGate Monitor Server software.
You should only change the sections of the SNMPJMXMapping.xml
file that set the SNMP version and define the targets.
. . . <MIBTree> . . . <notifications type="NOTIFICATIONS"> <notification version="2" enabled="true"> <targets> <target timeout="200" retry="0">localhost/162 </target> </targets> . . . </notification> <notification version="1" enabled="false"> <targets> <target>localhost/162 </target> </targets> . . . </notification> </notifications> </MIBTree>
The SNMP version is initially set based on the entry during installation. You can change it later by resetting the notification version 1 enabled
value and notification version 2 enabled
value. Set one to true
and the other to false
.
The targets that are defined for the enabled version are used. The targets for the disabled version are ignored.
An Oracle GoldenGate Monitor administrator can disable any category of alerts so that those alerts are not delivered to remote clients. You might, for example, want to disable alerts during planned outages, such as when processes are stopped during maintenance windows. Although the disabled alerts are not sent to remote clients, they will be recorded in the Oracle GoldenGate Monitor user interface.
To disable alerts:
Set the appropriate properties in the monitor.properties
file of Oracle GoldenGate Monitor Server to false.
To disable SMTP delivery, set monitor.smtp.alerts.enabled=false
To disable CLI delivery, set monitor.cli.alerts.enabled=false
To disable SNMP delivery, set monitor.snmp.alerts.enabaled=false
Stop and restart Oracle GoldenGate Monitor Server. See "Starting and Stopping Oracle GoldenGate Monitor Server" for directions on how to do this.
To enable the alerts again, set the properties back to true, and then stop and restart Oracle GoldenGate Monitor Server.