4 Configuring and Using Alerts

4.3.1.1 Command-Line Handler Arguments

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:

• dateTimeFormat

  This is the standard Java format argument described in Java documentation.

• executeIn

  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.

  quoted - Specifies whether quotation marks should be added.

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

4.3.2.1 Running on a Windows 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>

4.3.2.2 Running on a UNIX Host

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>

4.4.2.1 Setting the SNMP Version

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.

4.4.2.2 Setting the SNMP Targets

Define your targets within the <target> </target> tags by entering the host name and port number separated by a forward slash.