8 Configuring Watches and Notifications

The Watch and Notification component of the WebLogic Diagnostics Framework (WLDF) provides the means for monitoring server and application states and then sending notifications based on criteria set in the watches.Watches and notifications are configured as part of a diagnostic module targeted to one or more server instances in a domain.

Watches and notifications are described in the following sections:

Watches and Notifications

A watch identifies a situation that you want to trap for monitoring or diagnostic purposes. You can configure watches to analyze log records, data events, and harvested metrics. A watch is specified as a watch rule, which includes:

  • A watch rule expression

  • An alarm setting

  • One or more notification handlers

A notification is an action that is taken when a watch rule expression evaluates to true. WLDF supports the following types of notifications:

  • Java Management Extensions (JMX)

  • Java Message Service (JMS)

  • Simple Mail Transfer Protocol (SMTP), for example, e-mail

  • Simple Network Management Protocol (SNMP)

  • Diagnostic Images

You must associate a watch with a notification for a useful diagnostic activity to occur, for example, to notify an administrator about specified states or activities in a running server.

Watches and notifications are configured separately from each other. A notification can be associated with multiple watches, and a watch can be associated with multiple notifications. This provides the flexibility to recombine and re-use watches and notifications, according to current needs.

Overview of Watch and Notification Configuration

A complete watch and notification configuration includes settings for one or more watches, one or more notifications, and any underlying configurations required for the notification media, for example, the SNMP configuration required for an SNMP-based notification.

The main elements required for configuring watches and notifications in a WLDF system resource descriptor file, DIAG_MODULE.xml, are shown in Example 8-1. As the listing shows, the base element for defining watches and notifications is <watch-notification>. Watches are defined in <watch> elements, and notifications are defined in elements named for each of the types of notification, for example <jms-notification>, <jmx-notification>, <smtp-notification>, and <image-notification>.

Example 8-1 A Skeleton Watch and Notification Configuration (in DIAG_MODULE.xml)

<wldf-resource>
<!-- ----- Other system resource configuration elements ----- -->
  <watch-notification>
  <log-watch-severity>
     <!-- Threshold severity for a log watch to be evaluated further 
           (This can be narrowed further at the watch level.) -->
  </log-watch-severity>
    <!-- ----- Watch configuration elements: ----- -->
    <watch>
      <!-- A watch rule -->
    </watch>
    <watch>
      <!-- A watch rule -->
    </watch>
    <!-- Any other watch configurations -->

    <!-- ----- Notification configuration elements: ----- -->
    <!-- The following notification configuration elements show one of each 
         type of supported notifications. However, not all types are 
         required in any one system resource configuration, and multiples 
         of any type are permitted. -->
    <jms-notification>
      <!-- Configuration for a JMS-based notification; requires a
           corresponding JMS configuration via a jms-server element and a
           jms-system-resource element -->
    </jms-notification>

    <jmx-notification>
      <!-- Configuration for a JMX-based notification -->
    </jmx-notification>
    <smtp-notification>
      <!-- Configuration for an SMTP-based notification; requires a
           corresponding SMTP configuration via a mail-session element -->
    </smtp-notification>
    <snmp-notification>
      <!-- Configuration for an SNMP-based notification; requires a 
           corresponding SNMP agent configuration via an snmp-agent
           element -->
    </snmp-notification>
    <image-notification>
      <!-- Configuration for an image-based notification -->
    </image-notification>
  <watch-notification>
<!-- ----- Other configuration elements ----- -->
</wldf-resource>

Note:

While the notification media must be configured so they can be used by the notifications that depend on them, those configurations are not part of the configuration of the diagnostic module itself. That is, they are not configured in the <wldf-resource> element in the diagnostic module's configuration file.

Each watch and notification can be individually enabled and disabled by setting <enabled>true</enabled> or <enabled>false</enabled> for the individual watch and/or notification. In addition, the entire watch and notification facility can be enabled and disabled by setting <enabled>true</enabled> or <enabled>false</enabled> for all watches and notifications. The default value is <enabled>true</enabled>.

The <watch-notification> element contains a <log-watch-severity> sub-element, which affects how notifications are triggered by log-rule watches.

If the maximum severity level of the log messages that triggered the watch do not at least equal the provided severity level, then the resulting notifications are not fired. Note that this only applies to notifications fired by watches which have log rule types. Do not confuse this element with the <severity> element defined on watches. The <severity> element assigns a severity to the watch itself, whereas the <log-watch-severity> element controls which notifications are triggered by log-rule watches.

For information about how to configure watches and notifications using the Administration Console, see "Configure Watches and Notifications" in Oracle WebLogic Server Administration Console Help

Sample Watch and Notification Configuration

A complete configuration for a set of watches and notifications in a diagnostic module is shown in Example 8-2. The details of this example are explained in the following two sections:

Example 8-2 Sample Watch and Notification Configuration (in DIAG_MODULE.xml)

<?xml version='1.0' encoding='UTF-8'?> 
<wldf-resource xmlns="http://xmlns.oracle.com/weblogic/weblogic-diagnostics" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://xmlns.oracle.com/weblogic/weblogic-diagnostics/1.0/weblogic-diagnostics.xsd"> 
  <name>mywldf1</name> 
  <!-- Instrumentation must be configured and enabled for instrumentation 
       watches -->
  <instrumentation> 
    <enabled>true</enabled> 
    <wldf-instrumentation-monitor> 
      <name>DyeInjection</name> 
      <description>Dye Injection monitor</description> 
      <dye-mask xsi:nil="true"></dye-mask>       <properties>ADDR1=127.0.0.1</properties> 
    </wldf-instrumentation-monitor> 
  </instrumentation> 
  <!-- Harvesting does not have to be configured and enabled for harvester
       watches. However, configuring the Harvester can provide advantages;
       for example the data will be archived. -->
  <harvester> 
    <name>mywldf1</name> 
    <sample-period>20000</sample-period> 
    <harvested-type> 
      <name>weblogic.management.runtime.ServerRuntimeMBean</name> 
    </harvested-type> 
    <harvested-type> 
      <name>weblogic.management.runtime.WLDFHarvesterRuntimeMBean</name> 
    </harvested-type> 
  </harvester> 
  <!-- All watches and notifications are defined under the 
       watch-notification element -->
  <watch-notification> 
    <enabled>true</enabled> 
    <log-watch-severity>Info</log-watch-severity>
    <!-- A harvester watch configuration --> 
    <watch> 
      <name>myWatch</name> 
      <enabled>true</enabled> 
      <rule-type>Harvester</rule-type>
      <rule-expression>${com.bea:Name=myserver,Type=ServerRuntime//SocketsOpenedTotalCount} &gt;= 1</rule-expression>
      <alarm-type>AutomaticReset</alarm-type> 
      <alarm-reset-period>60000</alarm-reset-period> 
      <notification>myMailNotif,myJMXNotif,mySNMPNotif</notification> 
    </watch> 
    <!-- An instrumentation watch configuration --> 
    <watch> 
      <name>myWatch2</name> 
      <enabled>true</enabled> 
      <rule-type>EventData</rule-type> 
      <rule-expression>
      (MONITOR LIKE 'JDBC_After_Execute') AND
      (DOMAIN = 'MedRecDomain') AND
      (SERVER = 'medrec-adminServer') AND
      ((TYPE = 'ThreadDumpAction') OR (TYPE = TraceElapsedTimeAction')) AND
      (SCOPE = 'MedRecEAR')
      </rule-expression>
      <notification>JMXNotifInstr</notification> 
    </watch> 
    <!-- A log watch configuration -->
    <watch> 
      <name>myLogWatch</name> 
      <rule-type>Log</rule-type> 
      <rule-expression>MSGID='BEA-000360'</rule-expression> 
      <severity>Info</severity> 
      <notification>myMailNotif2</notification> 
    </watch>
    <!-- A JMX notification -->
    <jmx-notification> 
      <name>myJMXNotif</name> 
    </jmx-notification> 
    <!-- Two SMTP notifications -->
    <smtp-notification> 
      <name>myMailNotif</name> 
      <enabled>true</enabled> 
      <mail-session-jndi-name>myMailSession</mail-session-jndi-name> 
      <subject>This is a harvester alert</subject> 
      <recipient>username@emailservice.com</recipient> 
    </smtp-notification> 
    <smtp-notification> 
      <name>myMailNotif2</name> 
      <enabled>true</enabled> 
      <mail-session-jndi-name>myMailSession</mail-session-jndi-name> 
      <subject>This is a log alert</subject> 
      <recipient>username@emailservice.com</recipient> 
    </smtp-notification> 
    <!-- An SNMP notification -->
    <snmp-notification> 
      <name>mySNMPNotif</name> 
      <enabled>true</enabled> 
    </snmp-notification> 
  </watch-notification> 
</wldf-resource>