Configuring and Using the WebLogic Diagnostic Framework

Configuring Watches

The following topics describe the types of watches and their configuration options:

About the Types of Watches

WLDF provides three main types of watches, based on what the watch can monitor:

Harvester watches monitor the set of harvested MBeans in the local runtime MBean server.
Log watches monitor the set of messages generated into the server log.
Instrumentation (or Event Data) watches monitor the set of events generated by the WLDF Instrumentation component.

In the WLDF system resource configuration file for a diagnostic module, each type of watch is defined in a <rule-type> element, which is a child of <watch>. For example:

<watch>

<rule-type>Harvester</rule-type>

</watch>

Watches with different rule types differ in two ways:

The rule syntax for specifying the conditions being monitored are unique to the type.
Log and event watches are triggered in real time, whereas harvester watches are triggered only after the current harvest cycle completes.

Configuration Options Shared by all Types of Watches

All watches share certain configuration options:

Watch rule expression

In the diagnostic module configuration file, watch rule expressions are defined in <rule-expression> elements.
A watch rule expressions is a logical expression that specifies what significant events the watch is to trap. For information about the query language you use to define watch rules, including the syntax available for each type of watch rule, see WLDF Query Language.

Notifications associated with the watch

In the diagnostic module configuration file, notifications are defined in <notification> elements.
Each watch can be associated with one or more notifications that are triggered whenever the watch evaluates to true. The content of this element is a comma-separated list of notifications. For information about configuring notifications, see Configuring Notifications.

Alarm options

In the diagnostic module configuration file, alarm options are set using <alarm-type> and <alarm-reset-period> elements.
Watches can be specified to trigger repeatedly, or to trigger once, when a condition is met. For watches that trigger repeatedly, you can optionally define a minimum time between occurrences. The <alarm-type> element defines whether a watch automatically repeats, and, if so, how often. A value of none causes the watch to trigger whenever possible. A value of AutomaticReset also causes the watch to trigger whenever possible, except that subsequent occurrences cannot occur any sooner than the millisecond interval specified in the <alarm-reset-period>. A value of ManualReset causes the watch to fire a single time. After it fires, you must manually reset it to fire again. For example, you can use the WatchNotification runtime MBean to reset a manual watch. The default for <alarm-type> is None.

Severity options

Watches contain a severity value which is passed through to the recipients of notifications. The permissible severity values are as defined in the logging subsystem. The severity value is specified using sub-element <severity>. The default is Notice.

Enabled options

Each watch can be individually enabled and disabled, using the sub-element <enabled>. When disabled, the watch does not trigger and corresponding notifications do not fire. If the more generic watch/notification flag is disabled, it causes all individual watches to be effectively disabled (that is, the value of this flag on a specific watch is ignored).

Configuring Harvester Watches

A harvester watch can monitor any runtime MBean in the local runtime MBean server.

Note: If you define a watch rule to monitor an MBean (or MBean attributes) that the Harvester is not configured to harvest, the watch will work. The Harvester will "implicitly" harvest values to satisfy the requirements set in the defined watch rules. However, data harvested in this way (that is, implicitly for a watch) will not be archived. See Configuring the Harvester for Metric Collection, for more information about the Harvester.

Harvester watches are triggered in response to a harvest cycle. So, for harvester watches, the Harvester sample period defines a time interval between when a situation is identified and when it can be reported though a notification. On average, the delay will be SamplePeriod/2.

Listing 7-1, shows an example of a harvester watch that monitors several runtime MBeans.When the rule evaluates to true, six different notifications are sent: a JMX notification, an SMTP notification, an SNMP notification, an image notification, and JMS notifications for both a topic and a queue.

Note: In this example of a harvester watch, the Harvester is explicitly configured for this watched value. Therefore, Listing 7-1 below contains the appropriate harvester configuration elements.

The watch rule is a logical expression composed of four harvester variables. The rule has the form:

    ( (A >= 100) && (B > 0) ) || C || D.equals("active")

Each variable is of the form:

    {entityName}//{attributeName}

where {entityName} is the JMX ObjectName as registered in the runtime MBean server and {attributeName} is the name of an attribute defined on that MBean type.

Note: The comparison operators are qualified in order to be valid in XML.

Listing 7-1 Harvester Watch Example

<wldf-resource xmlns="http://www.bea.com/ns/weblogic/90/diagnostics" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.bea.com/ns/weblogic/90/diagnostics.xsd">

  <name>mywldf1</name>

  <harvester>
    <harvested-type>
      <name>myMBeans.MySimpleStandard</name>
      <harvested-instance>myCustomDomain:Name=myCustomMBean1
      </harvested-instance>
      <harvested-instance>myCustomDomain:Name=myCustomMBean2
      </harvested-instance>
    </harvested-type>
    <!-- Other Harvester configuration elements -->
  <harvester>

  <watch-notification>

    <watch>
      <name>simpleWebLogicMBeanWatchRepeatingAfterWait</name>
      <enabled>true</enabled>
      <rule-type>Harvester</rule-type>
      <rule-expression>
       (${mydomain:Name=WLDFHarvesterRuntime,ServerRuntime=myserver,Type=
       WLDFHarvesterRuntime,WLDFRuntime=WLDFRuntime//TotalSamplingTime}
          >= 100
           AND
          ${mydomain:Name=myserver,Type=
                   ServerRuntime//OpenSocketsCurrentCount} > 0)
           OR
         ${mydomain:Name=WLDFWatchNotificationRuntime,ServerRuntime=
             myserver,Type=WLDFWatchNotificationRuntime,
               WLDFRuntime=WLDFRuntime//Enabled} = true
           OR
         ${myCustomDomain:Name=myCustomMBean3//State} =
                 'active')
      </rule-expression>
      <severity>Warning</severity>
      <alarm-type>AutomaticReset</alarm-type>
      <alarm-reset-period>10000</alarm-reset-period>
      <notification>myJMXNotif,myImageNotif,
         myJMSTopicNotif,myJMSQueueNotif,mySNMPNotif,
         mySMTPNotif</notification>
    </watch>
    <!-- Other watch-notification configuration elements -->
  </watch-notification>

</wldf-resource>

This watch uses an alarm type of AutomaticReset, which means that it may be triggered repeatedly provided that the last time it was triggered was longer than the interval set as the alarm reset period (in this case 10000 milliseconds).

The severity level provided, Warning has no effect on the triggering of the watch, but will be passed on through the notifications.

Configuring Log Watches

Log watches are used to monitor the occurrence of specific messages and/or strings in the server log. Watches of this type are triggered as soon as the log messages is issued.

An example configuration for a log watch is shown in Listing 7-2.

Listing 7-2 Example Configuration for a Log Watch

<wldf-resource xmlns="http://www.bea.com/ns/weblogic/90/diagnostics" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.bea.com/ns/weblogic/90/diagnostics.xsd"> 
  <name>mywldf1</name>

  <watch-notification> 
    <enabled>true</enabled> 
    <log-watch-severity>Info</log-watch-severity>

    <watch> 
      <name>myLogWatch</name> 
      <rule-type>Log</rule-type> 
      <rule-expression>MSGID='BEA-000360'</rule-expression> 
      <severity>Info</severity> 
      <notification>myMailNotif2</notification> 
    </watch>

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

  </watch-notification>

</wldf-resource>

Configuring Instrumentation Watches

Instrumentation watches are used to monitor the events from the WLDF Instrumentation component. Watches of this type trigger as soon as the event is posted.

Listing 7-3 shows an example configuration for an instrumentation watch.

Listing 7-3 Example Configuration for an Instrumentation Watch

  <watch-notification>
    <watch>
    <name>myInstWatch</name>
    <enabled>true</enabled>
    <rule-type>EventData</rule-type>
    <rule-expression>
      (PAYLOAD &gt; 100000000) AND (MONITOR = 'Servlet_Around_Service')
    </rule-expression>
    <alarm-type xsi:nil="true"></alarm-type>
    <notification>mySMTPNotification</notification>
  </watch>

  <smtp-notification>
    <name>mySMTPNotification</name>
    <enabled>true</enabled>
    <mail-session-jndi-name>myMailSession</mail-session-jndi-name>
    <subject xsi:nil="true"></subject>
    <body xsi:nil="true"></body>
    <recipient>username@emailservice.com</recipient>
  </smtp-notification>

</watch-notification>

Defining Watch Rule Expressions

A watch rule expression encapsulates all information necessary for specifying a rule. For documentation on the query language you use to define watch rules, see WLDF Query Language.