10 Configuring Policies

When creating a policy, you must define its type in its rule type attribute. Policies with different rule types differ in two ways:

• The syntax for specifying the conditions being monitored are unique to the rule type.

• Log and instrumentation policies are triggered in real time, whereas scheduled policies are triggered by settings on the WLDFScheduleBean interface, described in Policy Schedule.

The way to define the rule type depends on the tool you use to create the policy:

• If you are using the WebLogic Server Administration Console or Fusion Middleware Control, the rule type is determined by the policy type you are creating. For each of the policy types you can choose in either console, the following table identifies the corresponding rule type and WLDFWatchBean.RuleType attribute value that is defined for that policy:

  Policy Type . . .	Rule Type	WLDFWatchBean.RuleType Value
  Smart Rule	Harvester	Harvester
  Calendar Based	Harvester	Harvester
  Collected Metrics	Harvester	Harvester
  Server Log	Log	Log
  Domain Log	Log	DomainLog
  Event Data	Instrumentation	EventData

  For information about choosing a policy type using the WebLogic Server Administration Console, see Create policies for a diagnostic system module in Oracle WebLogic Server Administration Console Online Help.

• If you are using WLST, REST, or JMX to configure a policy, you set the WLDFWatchBean.RuleType attribute as follows:

  Policy Type	Rule Type Attribute
  Scheduled policy	Harvester
  Log policy	Log — for server log monitoring DomainLog — for domain log monitoring
  Instrumentation	EventData — for instrumentation event monitoring

Policy expressions can be created using either of the following languages:

• Java Expression Language (EL) (recommended)

• WLDF query language (deprecated in WebLogic Server 12.2.1)

If you have diagnostic system modules created with a previous release of WebLogic Server, WLDF supports expressions that use the WLDF query language. If you are creating new policies for either an existing or a new diagnostic system module, Oracle strongly recommends using Java EL as the policy expression language.

For more information about Java (EL), see the JSR-000341 Expression Language 3.0 specification at https://jcp.org/aboutJava/communityprocess/final/jsr341/index.html.

A policy expression encapsulates all information necessary for specifying a rule that, when evaluated to true, causes the associated actions to be executed. When you use Java EL as the expression language, you can construct a policy expression that uses the following out-of-the-box resources to set the conditions that determine whether to fire an associated action:

• Beans

  A bean is a Java object that can represent nearly anything in the domain, such as metrics from MBeans, or structured data surfaced by other beans.

• Functions

  Functions are a set of operations that are provided either by EL itself, or by WLDF, that can be invoked on metric data.

• Smart rules

  Smart Rules are special set of functions that encapsulate more complex logic and monitoring capabilities, and have specialized support in both the WebLogic Server Administration Console and Fusion Middleware Control. They can be used by themselves, or with other expression components as part of a larger, more complex expression.

Each policy can be associated with one or more actions that are executed whenever the policy evaluates to true. For information about configuring actions, see Configuring Actions.

All scheduled policies must be configured with a schedule. Scheduling allows policies to be evaluated according to a calendar schedule, at a specific time, after a duration of time, or at timed intervals.

You configure a policy schedule by setting attributes on the WLDFScheduleBean interface, which is a property of the WLDFWatchBean. You can set these attributes using the WebLogic Server Administration Console, WLST, REST, or a JMX application. When you are configuring new policies, the WebLogic Server Administration Console and Fusion Middleware Control provide convenient assistants and workflows for configuring common scheduling scenarios.

Table 10-1 lists the attributes of the WLDFScheduleBean and their default values, which are the same as for the javax.ejb.ScheduleExpression interface. In addition, the syntax for specifying a value, range, list, or interval for a specific unit of time is also the same as that described for the ScheduleExpression interface. For more information, see http://docs.oracle.com/javaee/7/api/javax/ejb/ScheduleExpression.html.

second

0

minute

*/5

hour

*

dayOfWeek

*

dayOfMonth

*

month

*

year

*

timezone

A policy that has been evaluated to true is referred to as having been triggered. For policies that are run repeatedly, an alarm determines when a policy can be evaluated again after it has been triggered. If a policy is configured with an alarm, a triggered policy is not evaluated again until the alarm is reset. For policies that are evaluated repeatedly, you can optionally define a minimum time that must transpire after a policy has been triggered before the policy can be evaluated again.

An alarm is important to configure for a policy that is run repeatedly to prevent the associated actions from being executed too frequently, such as generating a flood of emails or JMX notifications. For example, if you have a scheduled policy that executes a scale up action on a dynamic cluster, you should set an alarm that delays evaluating the policy again until the dynamic cluster is fully scaled up and is processing incoming requests. This delay is referred to as the alarm reset period. Without a proper alarm reset period, the scale up action could be executed again prematurely and counterproductively.

To configure an alarm for a policy, you specify the following:

• The alarm type

• The alarm reset period

The following table lists and describes each of the available alarm types:

None

AutomaticReset

ManualReset

Note the following alarm state behaviors:

• When the alarm type is AutomaticReset, a policy enters the alarm state when triggered and stays in that state until the time interval specified by the alarm reset period has expired.

• If a policy is configured with a ManualReset alarm, the policy enters the alarm state when triggered, and remains in that state until you manually reset it.

• When a policy is in the alarm state, the policy is not evaluated again until the alarm is reset.

• If a policy's alarm type is None, the configured action can be executed every time that the policy is triggered. The alarm state is never set in these cases.

Whenever a policy is triggered, a message is automatically generated in the logging system. The severity option is an optional value you can configure that:

1. Gets assigned as the severity value of the log message generated in the logging system.

2. Is also passed to the actions that are configured with the policy.

The severity option must be one that is defined for the WebLogic logging service in the weblogic.logging.Severities class. The accepted values are Info, Notice, Warning, Error, Critical, Alert, and Emergency. The default is Notice.

Each policy can be individually enabled and disabled by using the Enabled attribute on that policy. The value you specify for this attribute is true or false. When disabled, a policy is not evaluated and its configured actions are not executed.

However, note that the WLDFWatchNotificationBean, which is the parent of all policy and action configurations in a diagnostic system module, also has an Enabled attribute. If the value of the WLDFWatchNotificationBean.Enabled attribute is false, all individual policies in the diagnostic system modules are disabled regardless of whether its policies are individually configured as enabled.

The simplest type of scheduled policy is the calendar based policy. You can use a calendar based policy to fire any associated actions according to the policy's schedule.

Calendar-based policies are simply scheduled policies with no associated expression. This enables purely schedule-driven action execution; that is, the ability to unconditionally perform a set of actions on a specified schedule. If no expression is provided, when the scheduled time occurs, the policy treats the empty expression as a true result and executes the associated actions.

The following example shows the configuration of a calendar based policy using WLST. This policy fires a scale up action at 3:00 a.m. on December 26.

calendarScaleUp=wn.lookupWatch('ChristmasReturnsScaleUpWatch')
if calendarScaleUp == None:
  print "Creating scale-up for the post-Christmas returns rush on Dec 26 at 3am"
  calendarScaleUp=wn.createWatch('ChristmasReturnsScaleUpWatch')
calendarScaleUp.setRuleType('Harvester')
calendarScaleUp.setExpressionLanguage('EL')
calendarScaleUp.getSchedule().setHour('3')
calendarScaleUp.getSchedule().setMinute('0')
calendarScaleUp.getSchedule().setSecond('0')
calendarScaleUp.getSchedule().setDayOfMonth('26')
calendarScaleUp.getSchedule().setMonth('Dec')
calendarScaleUp.setEnabled(false)
calendarScaleUp.addNotification(scaleUp)

Smart rules are prepackaged functions that greatly simplify the creation of policy expressions. The WebLogic Server Administration Console and Fusion Middleware Control, in particular, each contain a smart rule editor to greatly simplify the task of configuring a smart rule for the policy you are creating.

Smart rules perform a number of complex operations, but surface only a small number of configuration parameters that you set. Details about the specific low level metrics that are collected, how they are used, and so on, are hidden, thereby making them easy to use. Smart rules return only a Boolean value, which determines whether the policy is evaluated to true.

You use a smart rule as a predicate in policy expression by simply specifying the parameters required by that smart rule. For example, to evaluate whether a particular increase exists in the average thread pool queue length in the local server, you create a policy that specifies the ServerHighQueueLength smart rule as the policy expression and provide the following parameters:

• The sampling period for collecting the value of the ThreadPoolRuntimeMBean.QueueLength attribute

• Duration, or the most recent window of time, in which samples are retained

• A threshold value that establishes the maximum acceptable number of threads in the queue

The smart rule takes responsibility for sampling the appropriate metrics over the specified time interval, computing averages, comparing threshold values, and determining whether the smart rule evaluates to true.

Collected metrics based policies, which are a type of scheduled policy, can use WLDF-provided beans and functions within their policy expressions. These beans are JavaBean objects that can obtain access to common WebLogic Server JMX data sources, such as the following:

• WebLogic Server Runtime MBean Server

• Domain Runtime MBean Server

• JVM platform MBean server

The following sections explain how to configure collected metrics based policies using beans and functions:

• Using Beans

• Using Functions

Within the same diagnostics system module, the expression in one policy can reference other policies as beans within that expression. In this way, complex policy expressions can be reused and "chained" together to allow the state of one policy to be part of the expression of another. This allows more complex, interrelated policies to be written, while keeping such policy configurations more readable and maintainable.

To allow access to policy states within an expression, you can use the resource bean within the global bean name space for each policy. The resource bean supports a Map attribute named watches, where each key in the map is the name of a policy defined within the same diagnostics system module.

Each value in the policy's map is a bean representing the named policy. These policy beans support a simple Boolean alarm attribute, which has the following semantics:

• If the policy is configured with an alarm type other than None, the alarm attribute returns true if the policy is currently in the alarm state.

• If no alarm type is configured on the policy, the alarm attribute yields the most recently evaluated result.

• If the alarm attribute on a policy bean is accessed before the named policy has successfully completed an evaluation cycle, a NotEnoughDataException is thrown. This occurrence also has the effect of invalidating the expression during that evaluation cycle: the policy isn't disabled, but it is effectively a non-result when it occurs.