Configuring Policies and Actions

9 Configuring Policies and Actions

The Policies and Actions component of the WebLogic Diagnostics Framework (WLDF) provides the means for monitoring server and application states and then executing actions based on criteria set in the policies.Policies and actions are configured as part of a diagnostic module that is targeted to one or more server instances in a domain.

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.

The following sections give an overview of the Policies and Actions component, and also provide an example of a Policies and Actions configuration:

Policies and Actions
You can configure policies to analyze log records, data events, and harvested metrics.
Overview of Policies and Actions Configuration
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.
Sample Policies and Actions Configuration
A set of policies and actions is configured in a diagnostic module file named DIAG_MODULE.xml.

Policies and Actions

You can configure policies to analyze log records, data events, and harvested metrics.

A policy identifies a situation that you want to trap for monitoring or diagnostic purposes.

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 Policy-Based Scaling in 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.

Parent topic: Configuring Policies and Actions

Overview of Policies and Actions Configuration

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.

Parent topic: Configuring Policies and Actions

Sample Policies and Actions Configuration

A set of policies and actions is configured in a diagnostic module file named DIAG_MODULE.xml.

Example 9-2 shows a complete configuration. 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/2.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} &gt;= 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>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>

Parent topic: Configuring Policies and Actions