Configuring Actions

11 Configuring Actions

The WebLogic Diagnostics Framework (WLDF) provides several types of actions that can be executed when a policy evaluates to true, such as triggering an elastic scaling action, sending a JMS notification, executing an external command line script, and more.

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.

Actions Overview
An action is an operation that is executed when a policy expression evaluates to true. WLDF supports different types of action based on the delivery mechanism of the notification.
Configuring JMX Actions
WLDF issues JMX events when an associated policy is triggered for each defined JMX action. You can configure the JMX action to receive all the JMX notification and filter the output as required.
Configuring JMS Actions
You can configure JMS actions to send JMS notifications through the JMS topics or queues when the corresponding policy is triggered. You can define how the notification must be delivered such as defining the destination and the connection factory.
Configuring SNMP Actions
Simple Network Management Protocol (SNMP) actions are used to post SNMP traps when an associated policy is triggered. Provide the action name to define an SNMP action.
Configuring Log Actions
You can create a log action to send a customized message to the server log.
Configuring REST Actions
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.
Configuring SMTP Actions
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. You provide a list of recipients to whom the message is distributed through the configured SMTP session.
Configuring Image Actions
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.
Configuring Elastic Actions
WLDF provides scale up and scale down elastic actions that can be performed on dynamic clusters.
Configuring Script Actions
You can use the script action to execute an external command-line script. The script can be written in any scripting language.
Configuring Heap Dump Actions
You can use a heap dump action to capture heap dumps when certain runtime conditions, defined by a policy expression, are met. Each heap dump is produced in HPROF format, which you can analyze with tools such as the jmap utility, which is available in the JDK.
Configuring Thread Dump Actions
You can use a thread dump action to capture a specific number of thread dumps, separated by configured time interval, when the runtime conditions that are specified in a corresponding policy are met. Each thread dump file is produced in an individual text file.

Actions Overview

An action is an operation that is executed when a policy expression evaluates to true. WLDF supports different types of action based on the delivery mechanism of the notification.

Topics

The following sections contain background information pertaining to WLDF actions:

Types of Actions
Variables for Customizable Actions
The log, SMTP, and REST action types support the generation of customized strings that contain one or more of the variables listed in this topic.
Action Timeout
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.

Parent topic: Configuring Actions

Types of Actions

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)
Heap dump
Thread dump

In the configuration file for a diagnostic module, the different types of actions are identified by the following 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>
<heap-dump-action>
<thread-dump-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.

Parent topic: Actions Overview

Variables for Customizable Actions

The log, SMTP, and REST action types support the generation of customized strings that contain one or more of the variables listed in this topic.

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 the following table.

Table 11-1 Substitution Variables

Variable Name	Value
`WatchName`	Name of policy that corresponds to the action
`WatchRuleType`	Policy type (for example, `Harvester`, `Log`, or `EventData`)
`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 `None`, `AutomaticReset`, or `ManualReset`.
`WatchAlarmResetPeriod`	Alarm reset period configured on the `WLDFWatchNotificationRuntimeMBean`.
`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 . 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:

Parent topic: Actions Overview

Action Timeout

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

Parent topic: Actions Overview

Configuring JMX Actions

WLDF issues JMX events when an associated policy is triggered for each defined JMX action. You can configure the JMX action to receive all the JMX notification and filter the output as required.

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/2.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

Parent topic: Configuring Actions

Configuring JMS Actions

You can configure JMS actions to send JMS notifications through the JMS topics or queues when the corresponding policy is triggered. You can define how the notification must be delivered such as defining the destination and the connection factory.

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/2.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.

Parent topic: Configuring Actions

Configuring SNMP Actions

Simple Network Management Protocol (SNMP) actions are used to post SNMP traps when an associated policy is triggered. Provide the action name to define an SNMP action.To define an SNMP action, provide the 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 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/2.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)

Parent topic: Configuring Actions

Configuring Log Actions

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}

Parent topic: Configuring Actions

Configuring REST Actions

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

Parent topic: Configuring Actions

Configuring SMTP Actions

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. You provide a list of recipients to whom the message is distributed through the configured SMTP session.

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 subelement <mail-session-jndi-name>, and provide a list of at least one recipient using subelement <recipients>. An optional subject and/or body can be provided using subelements <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 Action (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/2.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 action 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@example.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

Parent topic: Configuring Actions

Configuring Image Actions

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 the 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 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 Action (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/2.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 Configuring and Capturing Diagnostic Images.

Parent topic: Configuring Actions

Configuring Elastic Actions

WLDF provides scale up and scale down 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.

Note:

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

Elastic Scaling Operations Cannot Be Cancelled After Starting
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.
Limiting Server Shutdown Time During Scale Down Operations
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.

Parent topic: Configuring Actions

Elastic Scaling Operations Cannot Be Cancelled After Starting

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.

Parent topic: Configuring Elastic Actions

Limiting Server Shutdown Time During Scale Down Operations

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

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 0.
`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.

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

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.

Parent topic: Configuring Elastic Actions

Configuring Script Actions

You can use the script action to execute an external command-line script. The script can be written in any scripting 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);

Parent topic: Configuring Actions

Configuring Heap Dump Actions

You can use a heap dump action to capture heap dumps when certain runtime conditions, defined by a policy expression, are met. Each heap dump is produced in HPROF format, which you can analyze with tools such as the jmap utility, which is available in the JDK.

You create a heap dump action by configuring the WLDFHeapDumpActionBean and the WLDFServerDiagnosticMBean in a domain scope diagnostic system module – that is, a diagnostic system modules that is deployed in the domain partition. You cannot use this action in a diagnostic system module that is scoped to a partition. When configuring a heap dump action, you can specify the following:

Whether or not to include only objects that can be referenced (that is, not garbage-collected, or awaiting garbage collection), which you specify in the LiveSetOnly attribute of the WLDFHeapDumpActionBean. The default value is true.
The location each server's diagnostic dumps directory where the heap dumps are stored. You can specify this directory in the DiagnosticDumpsDir attribute of the WLDFServerDiagnosticMBean.
The number of heap dump files that are retained, which prevents filling up the file system with generated heap dumps. You can specify the number in the MaxHeapDumpCount attribute of the WLDFServerDiagnosticMBean. The default value is 8.

The generated heap dump files are named using the following syntax:

HeapDump_$SERVER_$MODULE_$POLICY_$ACTION_$timestamp.hprof

In the preceding syntax:

$SERVER represents the name of the WebLogic Server instance that generated the heap dump.
$MODULE represents the name of the diagnostics system module that contains the action configuration.
$POLICY represents the name of the policy that executed the heap dump action.
$ACTION represents the name of the WLDFHeapDumpActionBean.
$timestamp represents time when the heap dump was generated, which takes the form of yyyy_mm_dd_HH_MM_SS.

Note:

Note the following:

Heap dumps may contain sensitive information. Therefore, make sure that you place appropriate access protections on the directories into which heap dumps are generated.
If a heap dump action is in progress, an attempt by another heap dump action to generate a heap dump is rejected and a message is generated in the server log.

For information about how to create and configure a heap dump action using the WebLogic Server Administration Console, see Create a heap dump action and Configure a heap dump action in Oracle WebLogic Server Administration Console Online Help.

The jmap utility is described in the Java SE 8 documentation, available at http://docs.oracle.com/javase/8/.

Example 11-6 An Example Configuration for a Heap Dump Action

The following WLST example shows the configuration of a heap dump action:

# Start an edit session in edit tree
edit() 
startEdit() 
cd("/")

if cmo.lookupWLDFSystemResource("mywldf") == None:
  print "Creating WLDF resource"
  cmo.createWLDFSystemResource("mywldf")

cd("/WLDFSystemResources/mywldf/WLDFResource/mywldf/WatchNotification/mywldf")

# Create a heap dump action
cmo.createHeapDumpAction('myHeapDump')
cd("HeapDumpActions/myHeapDump")
# Set it to capture a full heap, not just the live setLiveSetOnly - default is "true"
cmo.setLiveSetOnly(false)

save()
activate()

Parent topic: Configuring Actions

Configuring Thread Dump Actions

You can use a thread dump action to capture a specific number of thread dumps, separated by configured time interval, when the runtime conditions that are specified in a corresponding policy are met. Each thread dump file is produced in an individual text file.

You create a thread dump action by configuring the WLDFThreadDumpActionBean and the WLDFServerDiagnosticMBean in a domain scope diagnostic system module – that is, a diagnostic system modules that is deployed in the domain partition. You cannot use this action in a diagnostic system module that is scoped to a partition. When configuring a thread dump action, you specify the following:

The number of thread dumps to be captured, which you specify in the ThreadDumpCount attribute of the WLDFThreadDumpActionBean. The default value is 3.
The interval between successive thread dumps, which you specify in the ThreadDumpDelaySeconds attribute of the WLDFThreadDumpActionBean. The default value is 10 seconds.
The location each server's diagnostic dumps directory where the thread dumps are stored, which you can specify with the DiagnosticDumpsDir attribute of the WLDFServerDiagnosticMBean.
The number of thread dump files that are retained, which prevents filling up the file system with generated thread dumps. You specify the number using the MaxThreadDumpCount attribute of the WLDFServerDiagnosticMBean. The default value is 100.

The generated thread dump files are named using the following syntax:

HeapDump_$SERVER_$MODULE_$POLICY_$ACTION_$timestamp.hprof

In the preceding syntax:

$SERVER represents the name of the WebLogic Server instance that generated the thread dump.
$MODULE represents the name of the diagnostics system module that contains the action configuration.
$POLICY represents the name of the policy that executed the thread dump action.
$ACTION represents the name of the WLDFThreadDumpActionBean.
$timestamp represents time when the thread dump was generated, which takes the form of yyyy_mm_dd_HH_MM_SS.

Note:

Note the following:

Thread dumps may contain sensitive information. Therefore, make sure that you place appropriate access protections on the directories into which thread dumps are generated.
If a thread dump action is in progress, an attempt by another thread dump action to generate a thread dump is rejected and a message is generated in the server log.

For information about how to create and configure a thread dump action using the WebLogic Server Administration Console, see Create a thread dump action and Configure a thread dump action in Oracle WebLogic Server Administration Console Online Help.

Example 11-7 An Example Configuration for a Thread Dump Action

The following WLST example shows the configuration of a thread dump action:

# Start an edit session in edit tree
edit() 
startEdit() 
cd("/")

if cmo.lookupWLDFSystemResource("mywldf") == None:
  print "Creating WLDF resource"
  cmo.createWLDFSystemResource("mywldf")

cd("WLDFSystemResources/mywldf/WLDFResource/mywldf/WatchNotification/mywldf")

# Create a Thread Dump action
cmo.createThreadDumpAction('myThreadDump')
cd("ThreadDumpActions/myThreadDump")

# set it to capture 5 dumps at 30 second intervals
cmo.setThreadDumpCount(5)
cmo.setThreadDumpDelaySeconds(30)

save()
activate()

Parent topic: Configuring Actions