This chapter describes the types of actions available in the WebLogic Diagnostics Framework (WLDF) and their configuration options.
This chapter includes the following sections:
For information about how to create an action using the WebLogic Server Administration Console, see "Create actions for policies in a diagnostic system module" in Oracle WebLogic Server Administration Console Online Help.
The following section contain background information pertaining to WLDF actions:
An action is an operation that is executed when a policy expression evaluates to true. WLDF supports the following types of diagnostic actions, based on the delivery mechanism:
Java Management Extensions (JMX)
Java Message Service (JMS)
Simple Network Management Protocol (SNMP)
Simple Mail Transfer Protocol (SMTP)
Diagnostic image capture
Elasticity framework
REST
WebLogic logging system
WebLogic Scripting Tool (WLST)
In the configuration file for a diagnostic module, the different types of actions are identified by these elements in the config.xml file for the domain:
<jmx-notification>
<jms-notification>
<snmp-notification>
<smtp-notification>
<image-notification>
<scale-up-action>
<scale-down-action>
<rest-notification>
<log-action>
<script-action>
These action types all have <name> and <enabled> configuration options. The value of <name> is used as the value in a <notification> element for a policy, to map the policy to its corresponding action. The <enabled> element, when set to true, enables that action. In other words, the action is executed when an associated policy evaluates to true. Other than <name> and <enabled>, each action type is unique.
The log, SMTP, and REST action types support the generation of customized strings that contain one or more of the variables listed in Table 11-1. When a triggered policy invokes one of these action types, each variable used in the customized string that is generated by the action is replaced with the value shown in this table.
Table 11-1 Substitution Variables
| Variable Name | Value |
|---|---|
WatchName |
Name of policy that corresponds to the action |
WatchRuleType |
Policy type (for example, |
WatchRule |
Policy expression |
WatchTime |
Timestamp identifying when the corresponding policy was triggered |
WatchSeverityLevel |
Policy severity option |
WatchData |
Log message |
WatchAlarmType |
Specifies the policy alarm type, which can be |
WatchAlarmResetPeriod |
Alarm reset period configured on the |
WatchDomainName |
WebLogic domain name |
WatchServerName |
Server instance name |
Log, REST, and SMTP actions send different types of messages when executed. Each of these actions, while different, has one or more properties that support the use of one or more of the variables defined in Table 11-1. For example, an SMTP message body can be specified as follows to include the policy name, expression, and timestamp indicating when the policy was triggered:
"Test ${WatchName} with policy ${WatchRule} fired at ${WatchTime}."
For more information about using these substitution variables, see:
All WLDF actions support a timeout, which determines the time, in seconds, for the action to complete execution. By default, the timeout is 0, which disables the action timeout. You can specify the action timeout using the WLDFNotificationBean.Timeout attribute.
You can also set the timeout when configuring an action in either the WebLogic Server Administration Console or Fusion Middleware Control. For more information, see the following topics:
"Create actions for policies in a diagnostic system module" in Oracle WebLogic Server Administration Console Online Help
"Configure an action" in Administering Oracle WebLogic Server with Fusion Middleware Control
For each defined JMX action, WLDF issues JMX events (notifications) whenever an associated policy is triggered. Applications can register an action listener with the server's WLDFWatchNotificationSourceRuntimeMBean to receive all JMX notifications and filter the provided output. You can also specify a JMX "notification type" string that a JMX client can use as a filter.
Example 11-1 shows an example of a JMX action configuration.
Example 11-1 Example Configuration for a JMX Action
<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>
<watch-notification>
<!-- One or more policy configurations -->
<jmx-notification>
<name>myJMXNotif</name>
<enabled>true</enabled>
</jmx-notification>
<!-- Other action configurations -->
</watch-notification>
</wldf-resource>
Here is an example of a JMX action:
Notification name: myjmx called. Count= 42.
Watch severity: Notice
Watch time: Jul 19, 2005 3:40:38 PM EDT
Watch ServerName: myserver
Watch RuleType: Harvester
Watch Rule: ${com.bea:Name=myserver,Type=ServerRuntime//OpenSocketsCurrentCount} > 1
Watch Name: mywatch
Watch DomainName: mydomain
Watch AlarmType: None
Watch AlarmResetPeriod: 10000
JMS actions are used to post notifications to JMS topics or queues in response to the triggering of an associated policy. In the system resource configuration file, the elements <destination-jndi-name> and <connection-factory-jndi-name> define how the notification is to be delivered.
Example 11-2 shows two JMS actions that cause JMS notifications to be sent through the provided topics and queues using the specified connection factory. For this to work properly, JMS must be properly configured in the config.xml configuration file for the domain, and the JMS resource must be targeted to this server.
Example 11-2 Example JMS Actions
<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>
<watch-notification>
<!-- One or more policy configurations -->
<jms-notification>
<name>myJMSTopicNotif</name>
<destination-jndi-name>MyJMSTopic</destination-jndi-name>
<connection-factory-jndi-name>weblogic.jms.ConnectionFactory
</connection-factory-jndi-name>
</jms-notification>
<jms-notification>
<name>myJMSQueueNotif</name>
<destination-jndi-name>MyJMSQueue</destination-jndi-name>
<connection-factory-jndi-name>weblogic.jms.ConnectionFactory
</connection-factory-jndi-name>
</jms-notification>
<!-- Other action configurations -->
</watch-notification>
</wldf-resource>
The content of the action message gives details of the policy and action.
Simple Network Management Protocol (SNMP) actions are used to post SNMP traps in response to the triggering of an associated policy. To define an SNMP action you only have to provide an action name, as shown in Example 11-3. Generated traps contain the names of both the policy and action that caused the trap to be generated. For an SNMP trap to work properly, SNMP must be properly configured in the config.xml configuration file for the domain.
Example 11-3 An Example Configuration for an SNMP Notification
<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>
<watch-notification>
<!-- One or more policy configurations -->
<snmp-notification>
<name>mySNMPNotif</name>
</snmp-notification>
<!-- Other action configurations -->
</watch-notification>
</wldf-resource>
The trap resulting from the SNMP action configuration shown in Example 11-3 is of type 85. It contains the following values (configured values are shown in angle brackets "<>"):
.1.3.6.1.4.1.140.625.100.5 timestamp (e.g. Dec 9, 2004 6:46:37 PM EST
.1.3.6.1.4.1.140.625.100.145 domainName (e.g. mydomain")
.1.3.6.1.4.1.140.625.100.10 serverName (e.g. myserver)
.1.3.6.1.4.1.140.625.100.120 <severity> (e.g. Notice)
.1.3.6.1.4.1.140.625.100.105 <name> [of watch] (e.g.
simpleWebLogicMBeanWatchRepeatingAfterWait)
.1.3.6.1.4.1.140.625.100.110 <rule-type> (e.g. HarvesterRule)
.1.3.6.1.4.1.140.625.100.115 <rule-expression>
.1.3.6.1.4.1.140.625.100.125 values which caused rule to
fire (e.g..State =
null,weblogic.management.runtime.WLDFHarvesterRuntimeMBean.
TotalSamplingTime = 886,.Enabled =
null,weblogic.management.runtime.ServerRuntimeMBean.
OpenSocketsCurrentCount = 1,)
.1.3.6.1.4.1.140.625.100.130 <alarm-type> (e.g. None)
.1.3.6.1.4.1.140.625.100.135 <alarm-reset-period> (e.g. 10000)
.1.3.6.1.4.1.140.625.100.140 <name> [of notification]
(e.g.mySNMPNotif)
You can create a log action to send a customized message to the server log. The customized message can optionally include any of the variables described in Variables for Customizable Actions.
The following WLST example shows the configuration of a log action:
wn=res.getWatchNotification()
actionName="myaction"
action = wn.lookupLogAction(actionName);
if action is None:
action = wn.createScriptAction(actionName);
action.setMessage("Message with substitution on server ${WatchServerName} in domain ${WatchDomainName}");
action.setSubsystemName("SpecialLogAction);
action.setSeverity("Info");
When the preceding log action is executed, the custom message, shown in bold, uses variables to identify:
The WebLogic Server instance name, represented by the ${WatchServerName} variable
The WebLogic domain name, represented by the variable ${WatchDomainName}
You can use a REST action to send a notification to a REST endpoint that includes a customized message in the notification payload. You can configure the REST endpoint invocation for no authentication or basic authentication.
When configuring a REST action, you can create a customized set of notification properties that can optionally use any of the variables described in Variables for Customizable Actions. For example, the following WLST example shows the configuration of a REST action that sends a customized message:
wn = res.getWatchNotification();
#No Auth REST invocation
rest1 = wn.createRESTNotification('r1')
rest1.setEndpointURL("http://localhost:7001/rest-no-auth/resources/watch-listener")
customNotif = java.util.Properties()
customNotif.put('message','Policy ${WatchName} with rule ${WatchRule} fired.')
rest1.setCustomNotificationProperties(customNotif)
rest1.setEnabled(true)
#Basic Auth REST invocation
rest2 = wn.createRESTNotification('r2')
rest2.setEndpointURL("http://localhost:7001/rest-basic-auth/resources/watch-listener")
rest2.setHttpAuthenticationMode('Basic')
rest2.setHttpAuthenticationUserName('restuser1')
rest2.setHttpAuthenticationPassword('restuser1')
rest2.setEnabled(true)
When the preceding REST action is executed, the REST endpoint is invoked with a message, shown in bold, that identifies:
The name of the triggered policy that executed the corresponding REST action, represented by the ${WatchName} variable
The policy expression, represented by the ${WatchRule} variable
Simple Mail Transfer Protocol (SMTP) actions are used to send messages (e-mail) over the SMTP protocol in response to the triggering of an associated policy. To define an SMTP action, first configure the SMTP session. That configuration is persisted in the config.xml configuration file for the domain. In DIAG_MODULE.xml, you provide the configured SMTP session using sub-element <mail-session-jndi-name>, and provide a list of at least one recipient using sub-element <recipients>. An optional subject and/or body can be provided using sub-elements <subject> and <body> respectively. If these are not provided, they will be defaulted.
Example 11-4 shows an SMTP action that causes an SMTP (e-mail) message to be distributed through the configured SMTP session, to the configured recipients. In this action configuration, a custom subject and body are provided. If a subject or body are not specified, defaults are provided, showing details of the policy and action.
Example 11-4 Sample Configuration for SMTP Notification (in DIAG_MODULE.xml)
<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>
<watch-notification>
<!-- One or more policy configurations -->
<smtp-notification>
<name>mySMTPNotif</name>
<mail-session-jndi-name>MyMailSession</mail-session-jndi-name>
<subject>Critical Problem!</subject>
<body>A system issue occurred. Call Winston ASAP.
Reference number 81767366662AG-USA23.</body>
<recipients>administrator@myCompany.com</recipients>
</smtp-notification>
<!-- Other policy configurations -->
</watch-notification>
</wldf-resource>
The content of the action message gives details of the policy and action.
WLDF also supports customizing the subject and body elements in the sent email by using any of the variables described in Variables for Customizable Actions.
The following WLST example shows the configuration of an SMTP action that contains customized subject and body text. The subject and body of the message utilize variables to specify the policy name and the timestamp indicating when the policy was triggered:
smtp=wn.lookupSMTPNotification('smtp1')
if smtp is None:
smtp=wn.createSMTPNotification('smtp1')
smtp.setMailSessionJNDIName('test.MailSession')
smtp.setSubject("WatchRule ${WatchName} alert")
smtp.setBody("Test ${WatchName} with rule ${WatchRule} fired at ${WatchTime}.")
smtp.setRecipients(["john.smith@foo.com"])
When the preceding SMTP action is executed, an email is generated with a custom subject and body, shown in bold, that identifies:
The name of the policy that executed the SMTP action, represented by the variable ${WatchName}. This variable is used in both the subject and body.
The policy expression, represented by the ${WatchRule} variable
The timestamp identifying when the corresponding policy was triggered, represented by the ${WatchTime} variable
An image action causes a diagnostic image to be generated in response to the triggering of an associated policy. You can configure two options for image actions: a directory and a lockout period.
The directory name indicates where images will be generated. The lockout period determines the number of seconds that must elapse before a new image can be generated after the last one. This is useful for limiting the number of images that will be generated when there is a sequence of server failures and recoveries
You can specify the directory name relative to the DOMAIN_HOME\servers\SERVER_NAME. The default directory is DOMAIN_HOME\servers\SERVER_NAME\logs\diagnostic-images.
Image file names are generated using the current timestamp (for example, diagnostic_image_myserver_2005_08_09_13_40_34.zip), so an action can execute many times, resulting in a separate image file each time.
The configuration is persisted in the DIAG_MODULE.xml configuration file. Example 11-5 shows an image an action configuration that specifies that the lockout time will be two minutes and that the image will be generated to the DOMAIN_HOME\servers\SERVER_NAME\images directory.
Example 11-5 Sample Configuration for Image Notification (in DIAG_MODULE.xml)
<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>
<watch-notification>
<!-- One or more policy configurations -->
<image-notification>
<name>myImageNotif</name>
<enabled>true</enabled>
<image-lockout>2</image-lockout>
<image-directory>images</image-directory>
</image-notification>
<!-- Other action configurations -->
</watch-notification>
</wldf-resource>
For more information about Diagnostic Images, see Chapter 6, "Configuring and Capturing Diagnostic Images."
WLDF provides the following elastic actions that can be performed on dynamic clusters:
scale up — configured using the WLDFScaleUpActionBean
scale down — configured using the WLDFScaleDownActionBean
Each action bean has the following configuration attributes:
clusterName — The name of the dynamic cluster that needs to be scaled
scalingSize — The number of Managed Server instances by which the dynamic cluster needs to be scaled up or down
The scale up and scale down actions attempt to scale the dynamic cluster specified by the clusterName parameter, by the number of servers specified as the scalingSize value. WLDF interacts with the elasticity framework to scale the dynamic cluster accordingly.
Notes:
Note the following:To configure automated elasticity for a dynamic cluster, you must create a domain-scope diagnostic system module in which you define the scaling policy, along with its corresponding elastic action, and then target that diagnostic module to the Administration Server.
After a scale up or scale down action has been invoked, the scaling action can't be subsequently cancelled.
The following WLST snippet shows the commands for configuring a scale up action. In this example, the dynamic cluster myCluster is scaled up by one Managed Server instance:
wn=res.getWatchNotification()
scaleUp=wn.lookupScaleUpAction('scaleUp')
if scaleUp == None:
print "Creating scale up action”
scaleUp=wn.createScaleUpAction('scaleUp')
scaleUp.setScalingSize(1)
scaleUp.setClusterName(myCluster)
The following example shows the WLST commands for configuring a scale down action on myCluster:
wn=res.getWatchNotification()
scaleDown=wn.lookupScaleDownAction('scaleDown')
if scaleDown == None:
print "Creating scale down action”
scaleDown=wn.createScaleDownAction('scaleDown')
scaleDown.setScalingSize(1)
scaleDown.setClusterName(myCluster)
For complete details about using these elastic actions, see:
"Elastic Actions" in Configuring Elasticity in Dynamic Clusters for Oracle WebLogic Server
"Expanding or Reducing Dynamic Clusters" in Administering Clusters for Oracle WebLogic Server
Note that the moment a scaling operation has begun, regardless of whether it is a scale up or scale down operation, it cannot be cancelled. If you configure automated elasticity in a dynamic cluster, such as with calendar-based or policy-based scaling, the elasticity framework does not provide the means to cancel a scaling operation after it has been initiated.
Consequently, if a postprocessor script (invoked by a script interceptor) fails, the parts of the scaling operation that were completed can't be reverted. For more information about script interceptors and postprocessor scripts, see "Configuring the Script Interceptor" in Configuring Elasticity in Dynamic Clusters for Oracle WebLogic Server.
Shutting down servers during a scale down operation can take a significant amount of time, especially if there are unreplicated sessions. Until unreplicated sessions time out, which can potentially be a long time, the server will not be shut down.
To limit the length of time required to complete a scale down operation, you can configure the following attributes on the DynamicServersMBean:
| Attribute | Description |
|---|---|
DynamicClusterShutdownTimeoutSeconds |
Timeout period, in seconds, to use while gracefully shutting down a dynamic server instance. If the dynamic server instance does not shut down before the specified timeout period, then it will be forcibly shut down.
The default value is |
IgnoreSessionsDuringShutdown |
Specifies whether to ignore inflight HTTP requests while shutting down dynamic server instances. |
WaitForAllSessionsDuringShutdown |
Specifies whether to wait for all persisted and nonpersisted inflight HTTP sessions to complete before shutting down dynamic server instances. |
By specifying a timeout or ignoring inflight HTTP sessions during shutdown, the shutdown time can be limited. However, note that remaining inflight HTTP sessions may be lost.
You can use the script action to execute an external command line script, which can be written in any language. To set the execution environment in which the script is run, you can configure the following attributes of the WLDFScriptActionBean:
PathToScript — The full path to the script, which must be located in the DOMAIN_HOME/bin/scripts directory
WorkingDirectory — The directory from which the WebLogic Server process was run, which is typically the domain root directory.
Environment — A map of environment variables to set for the child process
Parameters — An array of parameters or command options to pass to the script
Timeout — The time, in seconds, for the script action to complete execution. By default, the timeout is 0, which disables the script action timeout.
When the script action is executed by a triggered policy, WLDF invokes the configured script, which is run with the identity of the configured script. The script process executes as a child process of the WebLogic Server process that spawned it. Therefore, the script process has the same operating system identity as the WebLogic Server process; however, it does not inherit any of the parent process environment.
The following example shows configuring a script action using WLST:
wn=res.getWatchNotification()
actionName="myaction"
action = wn.lookupScriptAction(actionName);
if action is None:
action = wn.createScriptAction(actionName);
action.setWorkingDirectory("somedir");
action.setPathToScript("myScript.sh");
action.setParameters(["param1", "param2"]);
action.setTimeout(300);