Note:
As of WebLogic Server 12.2.1, the terms watch and notification are replaced by policy and action, respectively. However, the definition of these terms has not changed.
This chapter includes the following sections:
A policy identifies a situation that you want to trap for monitoring or diagnostic purposes. You can configure policies to analyze log records, data events, and harvested metrics.
A policy includes:
A policy expression (with the exception of calendar-based policies)
The default language for policy expressions is the WLDF query language; however, the WLDF query language is deprecated. You can also use Java Expression Language (EL) for policy expressions.
An alarm setting
One or more action handlers
You can also configure policies to enable elasticity in dynamic clusters; that is, to automatically scale a dynamic cluster up or down by a specific number of server instances. You can define policies to enable two broad categories of elasticity:
Calendar-based scaling — Scaling operations on a dynamic cluster that are executed on a particular date and time.
Policy-based scaling — Scaling operations on a dynamic cluster that are executed in response to changes in demand.
Note:
To configure an elastic scaling policy for a dynamic cluster, you must create a domain-scope diagnostic system module in which you define the scaling policy, and then target that diagnostic module to the Administration Server.
For more information about enabling elasticity in WebLogic Server, including instructions for downloading and running a demonstration example, see Configuring Elasticity in Dynamic Clusters for Oracle WebLogic Server.
An action is an operation that is executed when a policy expression evaluates to true. WLDF supports the following types of actions:
Scaling a dynamic cluster
Java Management Extensions (JMX)
Java Message Service (JMS)
Simple Mail Transfer Protocol (SMTP), for example, e-mail
Simple Network Management Protocol (SNMP)
Diagnostic image
Log
REST
Script
Heap dump
Thread dump
You must associate a policy with an action for a useful diagnostic activity to occur; for example, to notify an administrator about specified states or activities in a running server.
Policies and actions are configured separately from each other. An action can be associated with multiple policies, and a policy can be associated with multiple actions. This provides the flexibility to recombine and re-use policies and actions, according to current needs.
A complete policy and action configuration includes settings for one or more policies, one or more actions, and any underlying configurations required for the action media; for example, the SNMP configuration required for an SNMP-based action.
The main elements required for configuring policies and actions in a WLDF system resource descriptor file, DIAG_MODULE.xml, are shown in Example 9-1. As the listing shows, the base element for defining policies and actions is <watch-notification>. Policies are defined in <watch> elements, and actions are defined in elements named for each of the types of action; for example, <jms-notification>, <jmx-notification>, <smtp-notification>, and <image-notification>.
Example 9-1 A Skeleton Policy and Action 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>
<wldf-resource>
<!-- ----- Other system resource configuration elements ----- -->
<watch-notification>
<log-watch-severity>
<!-- Threshold severity for a log policy to be evaluated further
(This can be narrowed further at the policy level.) -->
</log-watch-severity>
<!-- ----- Policy configuration elements: ----- -->
<watch>
<!-- A policy expression -->
</watch>
<watch>
<!-- A policy expression -->
</watch>
<!-- Any other policy configurations -->
<!-- ----- Action configuration elements: ----- -->
<!-- The following action configuration elements show one of each
type of supported actions. 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 action; 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 action -->
</jmx-notification>
<smtp-notification>
<!-- Configuration for an SMTP-based action; requires a
corresponding SMTP configuration via a mail-session element -->
</smtp-notification>
<snmp-notification>
<!-- Configuration for an SNMP-based action; requires a
corresponding SNMP agent configuration via an snmp-agent
element -->
</snmp-notification>
<image-notification>
<!-- Configuration for an image-based action -->
</image-notification>
<watch-notification>
<!-- ----- Other configuration elements ----- -->
</wldf-resource>
Note:
While the notification media must be configured so they can be used by the actions 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 policy and action can be individually enabled and disabled by setting <enabled>true</enabled> or <enabled>false</enabled> for the individual policy or action. In addition, the entire policy and action facility can be enabled and disabled by setting <enabled>true</enabled> or <enabled>false</enabled> for all policies and actions. The default value is <enabled>true</enabled>.
The <watch-notification> element contains a <log-watch-severity> sub-element, which affects how actions are executed by log policies.
If the maximum severity level of the log messages that triggered the policy do not at least equal the provided severity level, then the resulting actions are not executed. Note that this only applies to actions executed by log policies. Do not confuse this element with the <severity> element defined on policies. The <severity> element assigns a severity to the policy itself, whereas the <log-watch-severity> element controls which actions are executed by log-type policies.
For information about how to configure policies and actions using the WebLogic Server Administration Console, see "Configure policies and actions" in Oracle WebLogic Server Administration Console Online Help.
A complete configuration for a set of policies and actions in a diagnostic module is shown in Example 9-2. The details of this example are explained in the following topics:
Example 9-2 Sample Policies and Actions 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
policies -->
<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
policies. 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 policies and actions are defined under the
watch-notification element -->
<watch-notification>
<enabled>true</enabled>
<log-watch-severity>Info</log-watch-severity>
<!-- A harvester policy configuration -->
<watch>
<name>myWatch</name>
<enabled>true</enabled>
<rule-type>Harvester</rule-type>
<rule-expression>${com.bea:Name=myserver,Type=ServerRuntime//SocketsOpenedTotalCount} >= 1</rule-expression>
<alarm-type>AutomaticReset</alarm-type>
<alarm-reset-period>60000</alarm-reset-period>
<notification>myMailNotif,myJMXNotif,mySNMPNotif</notification>
</watch>
<!-- An instrumentation policy 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 policy 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 actions -->
<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>[email protected]</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>[email protected]</recipient>
</smtp-notification>
<!-- An SNMP notification -->
<snmp-notification>
<name>mySNMPNotif</name>
<enabled>true</enabled>
</snmp-notification>
</watch-notification>
</wldf-resource>