1. Configuring and Using the Diagnostics Framework for Oracle WebLogic Server
  2. Understanding WLDF Configuration

5 Understanding WLDF Configuration

The WebLogic Diagnostics Framework (WLDF) provides several features for generating, gathering, analyzing, and persisting diagnostic data from WebLogic Server instances and from applications deployed to them.For server-scoped diagnostics, some WLDF features are configured as part of the configuration for a server in a domain. Other features are configured as system resource descriptors that can be targeted to servers (or clusters). For application-scoped diagnostics, diagnostic features are configured as resource descriptors for the application.

For general information about WebLogic Server domain configuration, see Understanding Oracle WebLogic Server Domains in Understanding Domain Configuration for Oracle WebLogic Server.

  • Configuration MBeans and XML
    WLDF is configured using configuration MBeans (Managed Beans), and the configuration is persisted in the XML configuration files. The configuration MBeans are instantiated at startup, based on the configuration settings in config.xml. When you modify a configuration by changing the values of MBean attributes, those changes are persisted in the XML files.
  • Tools for Configuring WLDF
    You can configure the WLDF in several ways such as using the built-in diagnostic modules, WebLogic Administration Console, WebLogic Scripting Tool (WLST), JMX and WLDF configuration beans, and editing the XML configuration files.
  • How WLDF Configuration Is Partitioned
    You can use WLDF to perform diagnostics tasks for server instances, clusters, and for applications.
  • Configuring Diagnostic Image Capture and Diagnostic Archives
    Configure the Diagnostic Image Capture and Diagnostic Archive components in the config.xml file for a domain. The server configuration details are defined in the <server-diagnostic-config > element of the XML configuration file.
  • Configuring Diagnostic Image Capture for Java Flight Recorder
    The JFR file contains data for all events procedures that are enabled. When WebLogic Server is configured with a supported version of Oracle HotSpot and Java Flight Recorder is enabled, the JFR file is automatically included in the diagnostic image capture.
  • Configuring Diagnostic System Modules
    To configure and use the Instrumentation, Harvester, and Policies and Actions components at the server level, you must first create a system resource called a diagnostic system module, which will contain the configurations for all those components. The configuration of diagnostic system module is defined in a resource descriptor.
  • Configuring Diagnostic Modules for Applications
    WLDF supports the ability to configure instrumentation of an application by means of a diagnostic application module. A diagnostic application module is similar to a diagnostic system module, with the exception that you configure it in an XML descriptor file that you package with the application archive file.
  • WLDF Configuration MBeans and Their Mappings to XML Elements
    The set of WLDF configuration MBeans, along with the diagnostic system module beans for WLDF objects, are organized into a specific hierarchy in a WebLogic domain.

Configuration MBeans and XML

WLDF is configured using configuration MBeans (Managed Beans), and the configuration is persisted in the XML configuration files. The configuration MBeans are instantiated at startup, based on the configuration settings in config.xml. When you modify a configuration by changing the values of MBean attributes, those changes are persisted in the XML files.

Configuration MBean attributes map directly to configuration XML elements. For example, the Enable attribute of the WLDFInstrumentationBean maps directly to the <enabled> sub-element of the <instrumentation> element in the resource descriptor file (configuration file) for a diagnostic module. If you change the value of the MBean attribute, the content of the XML element is changed when the configuration is saved. Conversely, if you were to edit an XML element in the configuration file directly (which is not recommended), the change to an MBean value would take effect after the next session is started.

For more information about WLDF Configuration MBeans, see WLDF Configuration MBeans and Their Mappings to XML Elements. For general information about how MBeans are implemented and used in WebLogic Server, see Understanding WebLogic Server MBeans in Developing Custom Management Utilities Using JMX for Oracle WebLogic Server.

Parent topic: Understanding WLDF Configuration

Tools for Configuring WLDF

You can configure the WLDF in several ways such as using the built-in diagnostic modules, WebLogic Administration Console, WebLogic Scripting Tool (WLST), JMX and WLDF configuration beans, and editing the XML configuration files.

Refer to the following sections for more information about the tools:

  • Use the built-in diagnostic system modules, which provide a simple and easy-to-use mechanism for performing basic health and performance monitoring of a WebLogic Server instance. See Using the Built-in Diagnostic System Modules.

  • Use the WebLogic Server Administration Console to configure WLDF for server instances and clusters. See Configure the WebLogic Diagnostics Framework in the Oracle WebLogic Server Administration Console Online Help.

  • Write scripts to be run in the WebLogic Scripting Tool (WLST). For specific information about using WLST with WLDF, see WebLogic Scripting Tool Examples. Also see Introduction in Understanding the WebLogic Scripting Tool for general information about using WLST.

  • Configure WLDF programmatically using JMX and the WLDF configuration MBeans. See Configuring and Using WLDF Programmatically for specific information about programming WLDF. See MBean Reference for Oracle WebLogic Server and browse or search for specific MBeans for programming reference.

  • Edit the XML configuration files directly. This documentation explains many configuration tasks by showing and explaining the XML elements in the configuration files. The XML is easy to understand, and you can edit the configuration files directly, although it is recommended that you do not. (If you have a good reason to edit the files directly, you should first generate the XML files by configuring WLDF in the WebLogic Server Administration Console. Doing so provides a blueprint for valid XML.)

    Note:

    If you make changes to a configuration by editing configuration files, you must restart the server for the changes to take effect.

Parent topic: Understanding WLDF Configuration

How WLDF Configuration Is Partitioned

You can use WLDF to perform diagnostics tasks for server instances, clusters, and for applications.

Parent topic: Understanding WLDF Configuration

Server-Level Configuration

You configure the following WLDF components as part of a server instance in a domain. The configuration settings are controlled using MBeans and are persisted in the domain's config.xml file.

  • Diagnostic Image Capture

  • Diagnostic Archives

See Configuring Diagnostic Image Capture and Diagnostic Archives.

You configure the following WLDF components as the parts of one or more diagnostic system modules that can be deployed to one or more server instances or clusters. These configuration settings are controlled using beans and are persisted in one or more diagnostic resource descriptor files (configuration files) that can be targeted to one or more server instances or clusters.

  • Harvester (for collecting metrics)

  • Policies and Actions

  • Instrumentation

See Configuring Diagnostic System Modules.

Parent topic: How WLDF Configuration Is Partitioned

Application-Level Configuration

You can use the WLDF Instrumentation component with applications, as well as at the server level. The Instrumentation component is configured in a resource descriptor file deployed with the application in the application's archive file. See Configuring Diagnostic Modules for Applications.

Parent topic: How WLDF Configuration Is Partitioned

Configuring Diagnostic Image Capture and Diagnostic Archives

Configure the Diagnostic Image Capture and Diagnostic Archive components in the config.xml file for a domain. The server configuration details are defined in the <server-diagnostic-config > element of the XML configuration file.

The <server-diagnostic-config> element is a child of the <server> element in a domain, as shown in Example 5-1.

Example 5-1 Sample WLDF Configuration Information in the config.xml File for a Domain

<domain>
  <server>
    <name>myserver</name>
    <server-diagnostic-config>
      <image-dir>logs/diagnostic_images</image-dir>
      <image-timeout>3</image-timeout>
      <diagnostic-store-dir>data/store/diagnostics</diagnostic-store-dir>
      <diagnostic-data-archive-type>FileStoreArchive
      </diagnostic-data-archive-type>
    </server-diagnostic-config>
  </server>
  <!-- Other server elements to configure other servers in this domain -->
  <!-- Other domain-based configuration elements, including references to 
       WLDF system resources, or diagnostic system modules.  -->
</domain>

Note:

If WebLogic Server is configured with Oracle HotSpot, and Java Flight Recorder is enabled, the diagnostic image capture can optionally include a Java Flight Recorder file, also called a JFR file, that includes WebLogic Server events. The JFR file can then be viewed in Java Mission Control. See Using WLDF with Java Flight Recorder.

See the following topics:

Parent topic: Understanding WLDF Configuration

Configuring Diagnostic Image Capture for Java Flight Recorder

The JFR file contains data for all events procedures that are enabled. When WebLogic Server is configured with a supported version of Oracle HotSpot and Java Flight Recorder is enabled, the JFR file is automatically included in the diagnostic image capture.

The amount of WebLogic Server event data that is included in the JFR file is determined by the configuration of the WLDF diagnostic volume.

Note:

Note the following:

To include WebLogic Server event data in the JFR file:

  1. Ensure that WebLogic Server is configured with Oracle HotSpot, which installed separately from WebLogic Server.

    See Planning the Oracle WebLogic Server Installation in Installing and Configuring Oracle WebLogic Server and Coherence.

  2. Ensure that Java Flight Recorder is enabled.

    In a default installation of Oracle HotSpot with WebLogic Server, Java Flight Recorder is disabled. For information about enabling Java Flight Recorder with HotSpot and WebLogic Server, see Using Java Flight Recorder with Oracle HotSpot.

  3. Set the WLDF diagnostic volume as appropriate. For general use, Oracle recommends the default setting of Low. However, you can increase the volume of WebLogic Server event data that is generated, as appropriate, by setting the volume to Medium or High.

    Note that the WLDF diagnostic volume setting has no impact on data recorded for other event producers, such as the JVM.

    See Configure WLDF diagnostic volume in Oracle WebLogic Server Administration Console Online Help.

Note:

If the WLDF diagnostic volume is set to Off, and Java Flight Recorder has not been explicitly disabled, the JFR file continues to include JVM event data and is always included in the diagnostic image capture.

Parent topic: Understanding WLDF Configuration

Configuring Diagnostic System Modules

To configure and use the Instrumentation, Harvester, and Policies and Actions components at the server level, you must first create a system resource called a diagnostic system module, which will contain the configurations for all those components. The configuration of diagnostic system module is defined in a resource descriptor.

The diagnostic system module created at the server level contains the configurations for the components. When creating a diagnostic system module, note the following:

  • Diagnostic system modules are globally available for targeting to servers and clusters configured in a domain.

  • In a given domain, you can create multiple diagnostic system modules with distinct configurations.

  • You can target multiple diagnostic system modules to any given server or cluster.

  • WLDF Runtime Control allows you to dynamically enable or disable a diagnostic system module without changing the domain configuration.

  • Runtime control also allows you to deploy, activate, deactivate, and undeploy a diagnostic system module on-the-fly that is not defined in the domain configuration.

The following sections described the configuration of diagnostic system modules:

Parent topic: Understanding WLDF Configuration

About the Resource Descriptor

A diagnostic system module has a corresponding resource descriptor that defines the diagnostic module's configuration. A resource descriptor can be either configured or external:

  • A configured resource descriptor is one that is defined as part of the domain configuration, and exists as a file in the DOMAIN_HOME/config/diagnostics directory. A configured resource descriptor is referenced by the domain config.xml file, and the corresponding diagnostic system module:

    • Is persisted in the domain configuration.

    • Is available to all servers and clusters in the domain.

    • Can be targeted to a server or cluster through the domain configuration.

    • Can be activated or deactivated dynamically using Runtime Control, regardless of whether it is explicitly targeted to a server or cluster.

    Any dynamic changes made to the activation state of the diagnostic system module are not persisted across server restarts.

  • An external resource descriptor is one that is not referenced by the domain config.xml file; that is, it is defined outside the domain configuration. The diagnostic system module that is configured by an external resource descriptor may be deployed and activated on a server using Runtime Control. However, this diagnostic system module:

    • Is not persisted in the domain configuration (that is, it is not referenced by the domain config.xml file.

    • Can be deployed, activated, and deactivated only dynamically.

    • Cannot have its deployment and activation state persisted in the domain configuration.

    • Remains in memory only until the server or cluster on which it is activated is shut down.

    • Cannot be automatically available on server restart.

    An external resource descriptor may exist in a file located outside the DOMAIN_HOME/config/diagnostics directory, or may be passed as a String object using the WLDF Runtime Control API (see Creating a Diagnostic System Module Based on an External Resource Descriptor).

Note:

The configuration of a diagnostic module conforms to the diagnostics.xsd schema, available at http://xmlns.oracle.com/weblogic/weblogic-diagnostics/2.0/weblogic-diagnostics.xsd.

Except for the name and list of targets for the diagnostic system module, all configuration information for a diagnostic system module is contained in its resource descriptor file. Example 5-2 shows portions of the descriptor file for a diagnostic system module named myDiagnosticModule.

Example 5-2 Sample Structure of a Diagnostic System Module Descriptor File, MyDiagnosticModule.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>MyDiagnosticModule</name>
  <instrumentation>
    <!-- Configuration elements for zero or more diagnostic monitors -->
  </instrumentation>
  <harvester>
    <!-- Configuration elements for harvesting metrics from zero or more 
         MBean types, instances, and attributes -->
  </harvester>
  <watch-notification>
    <!-- Configuration elements for one or more policies and one or more 
         actions-->
  </watch-notification>
</wldf-resource>

Parent topic: Configuring Diagnostic System Modules

WLDF Runtime Control

WLDF Runtime Control allows you to control the activation or deactivation of diagnostics system modules dynamically at run time without making a change to the domain configuration. This allows you to perform specific, targeted diagnostic analysis tasks, and optionally of limited duration, without interfering with the operation of the server instances themselves.

You can use Runtime Control to do the following:

  • Dynamically activate and deactivate diagnostic system modules that are persisted in the domain configuration without restarting the servers or clusters to which they are targeted.

  • Dynamically deploy, activate, deactivate, and undeploy diagnostic system modules that are configured by an external resource descriptor.

Note:

Note the following:

  • Changes applied to diagnostic system modules using Runtime Control, whether defined by configured or external resource descriptors, are not persisted. When a server instance is restarted, that server returns to its configured state, and any changes prior to that restart that were made using Runtime Control are lost.

  • If you use the Runtime Control to activate a diagnostic system module that is based on an external resource descriptor (see Creating a Diagnostic System Module Based on an External Resource Descriptor), the diagnostic resource name that you specify in the createSystemResourceControl() command to create that diagnostic system module is used as the WLDF Module name in Harvester records in the archive.

Parent topic: Configuring Diagnostic System Modules

Creating a Diagnostic System Module Based on a Configured Resource Descriptor

You create a diagnostic system module based on a configured resource descriptor using either the WebLogic Server Administration Console or the WebLogic Scripting Tool (WLST). It is created as a WLDFResourceBean, and the configuration is persisted in a resource descriptor file named DIAG_MODULE.xml, where DIAG_MODULE is the name of the diagnostic system module. You can specify a name for the descriptor file, but it is not required. If you do not provide a file name, a file name is generated based on the value in the descriptor file's <name> element. The file is created by default in the DOMAIN_HOME\config\diagnostics directory, and a reference to the module is added to the domain's config.xml file.

Note:

Oracle recommends that you do not write XML configuration files directly. But if you have a valid reason to do so, you should first create a diagnostic module from the Console. That way, you can start with the valid XML that the Console creates. For instructions, see Create diagnostic system modules in the Oracle WebLogic Server Administration Console Online Help.

The config.xml file can contain references to multiple diagnostic system modules, in one or more <wldf-system-resource> elements. The <wldf-system-resource> element includes the name of the diagnostic system module file and the list of servers and clusters to which the module is targeted.

For example, Example 5-3 shows a config.xml file with a module named myDiagnosticModule targeted to the server myserver and another module named newDiagnosticMod targeted to servers myserver and ManagedServer2. Note that myDiagnosticModule and newDiagnosticMod are both targeted to myserver.

Example 5-3 Sample WLDF Configuration Information in the config.xml File for a Domain

<domain>
  <!-- Other domain-level configuration elements --> 
  <wldf-system-resource 
         xmlns="http://xmlns.oracle.com/weblogic/weblogic-diagnostics">
    <name>myDiagnosticModule</name>
    <target>myserver</target>
    <descriptor-file-name>diagnostics/MyDiagnosticModule.xml
    </descriptor-file-name>
    <description>My diagnostic module</description>
  </wldf-system-resource>
  <wldf-system-resource>
    <name>newDiagnosticMod</name>
    <target>myserver,ManagedServer2</target>
    <descriptor-file-name>diagnostics/newDiagnosticMod.xml
    </descriptor-file-name>
    <description>A diagnostic module for my managed servers</description>
  </wldf-system-resource>
<!-- Other WLDF system resource configurations -->
</domain>

The relationship of the config.xml file and the MyDiagnosticModule.xml file is shown in Figure 5-1.

Figure 5-1 Relationship of config.xml to System Descriptor File

Description of Figure 5-1 follows
Description of "Figure 5-1 Relationship of config.xml to System Descriptor File"

For instructions on creating a diagnostic system module that is persisted in the domain, see Create diagnostic system modules in the Oracle WebLogic Server Administration Console Online Help.

Parent topic: Configuring Diagnostic System Modules

Creating a Diagnostic System Module Based on an External Resource Descriptor

WLDF provides the following API that you can use to pass an external resource descriptor and create a diagnostic system module on-the-fly. You can use this API to dynamically create and activate a diagnostic system module for a server, but neither its deployment nor activation state is persisted when the servers or clusters on which it was activated are rebooted. This API is provided by the following MBeans:

  • weblogic.management.runtime.WLDFControlRuntimeMBean

  • weblogic.management.runtime.WLDFSystemResourceControlRuntimeMBean

Using this API, you can pass the resource descriptor as a String object on-the-fly. For ease-of-use, WLDF also provides the following WLST commands, which you can use with a resource descriptor file that exists externally to the domain configuration:

  • createSystemResourceControl() — Creates (deploys) a diagnostics system module on-the-fly using a specified descriptor file.

  • destroySystemResourceControl() — Destroys (undeploys) a diagnostics system module previously created on-the-fly.

Externally configured diagnostic system modules that are deployed and activated in a server or cluster are automatically destroyed when that server or cluster is shut down.

If you activate a diagnostic system module that is based on an external resource descriptor, the diagnostic resource name that you specify in the createSystemResourceControl command is used as the module name. For example, this is the name that appears in the WLDF Module column when displaying the contents of the Harvester archive in the WebLogic Server Administration Console. For more information about the createSystemResourceControl command, see Diagnostics Commands in WLST Command Reference for WebLogic Server.

For an example of using WLST to create, activate, and destroy a diagnostic system module that is based on an external resource descriptor, see Using WLST to Activate and Deactivate Diagnostic System Modules.

Parent topic: Configuring Diagnostic System Modules

Targeting a Diagnostic System Module to a Server or Cluster

A diagnostic system module can be targeted by the domain config.xml file to zero, one, or more servers or clusters. In addition, a given server can have multiple modules targeted to it simultaneously. Typically you create multiple modules that monitor different aspects of your system. You can then choose which modules to target to a server or cluster, based on what you want to monitor at that time.

Because you can target the same module to multiple servers or clusters, you can write general purpose modules that you want to use across a domain.

You can change the target of a diagnostic module without restarting the server instances to which it is targeted or untargeted. This gives you considerable flexibility in writing and using diagnostic monitors that address a specific diagnostic goal, without interfering with the operation of the server instances themselves.

For information about how to use the WebLogic Server Administration Console to target a diagnostic system module that is persisted in the domain configuration, see Target and untarget diagnostic system modules in Oracle WebLogic Server Administration Console Online Help.

Note:

You cannot use the WebLogic Server Administration Console to target diagnostic system modules that are configured by an external descriptor. However, you can use WLST as described in Using WLST to Activate and Deactivate Diagnostic System Modules.

Parent topic: Configuring Diagnostic System Modules

Dynamically Activating or Deactivating Diagnostic System Modules

After you configure a diagnostic system module, you can activate or deactivate it without making a configuration change or rebooting the server instance to which it is targeted. This capability gives you control over the operative state of diagnostic system modules without restarting the targeted server or cluster instance or making a change to the domain configuration.

Because the domain configuration and all resource files are replicated to all servers in the domain, all configured WLDF resources are available for dynamic activation and deactivation on all servers in the domain. Note that if you dynamically activate or deactivate a diagnostics system module, and restart the targeted server, the module's activation state is reverted to whatever is configured in the domain.

For information about using this capability in the WebLogic Server Administration Console for diagnostic system modules that are persisted in the domain configuration, see Dynamically activate or deactivate a diagnostic system module in Oracle WebLogic Server Administration Console Online Help. (Note that you cannot use the WebLogic Server Administration Console to dynamically activate or deactivate diagnostic system modules that are configured by an external descriptor.)

You can also use WLST to dynamically activate or deactivate diagnostic system modules, including those configured by an external descriptor, as described in Using WLST to Activate and Deactivate Diagnostic System Modules.

Parent topic: Configuring Diagnostic System Modules

Using WLST to Activate and Deactivate Diagnostic System Modules

You can also use WLST to dynamically activate or deactivate a diagnostic system module. This capability is provided by the WLST commands listed and described in Table 5-1:

Table 5-1 WLST Commands to Dynamically Activate and Deactivate Diagnostic Modules

Command Summary
enableSystemResource

Enables a diagnostic system module on a WebLogic Server instance.
disableSystemResource

Disables a diagnostic system module on a WebLogic Server instance.
createSystemResourceControl

Creates a diagnostics system module from an external diagnostic descriptor file. Note that the diagnostics system module remains in memory only until the server is shut down and is not deployed the next time the server is restarted.
destroySystemResourceControl

Destroys, or undeploys, a diagnostics system module configured in an external diagnostic descriptor without changing the domain configuration.
listSystemResourceControls

Lists the diagnostic system modules currently configured on a WebLogic Server instance.

For complete details about these WLST commands, see Diagnostics Commands in WLST Command Reference for WebLogic Server.

Parent topic: Configuring Diagnostic System Modules

Example

This section gives an example of the steps for using WLST to dynamically activate and deactivate the following diagnostic system modules:

  • Module-0, configured in the domain and defined by the resource descriptor file Module-0-3905.xml located in the DOMAIN_HOME/config/diagnostics directory

  • Module-1, configured in the domain and defined by the resource descriptor file Module-0-3905.xml located in the DOMAIN_HOME/config/diagnostics directory

  • External-1, not a part of the domain configuration, but defined by the external resource descriptor external-wldf. This external resource descriptor is configured in the file external-wldf.xml, which is external to the domain configuration.

These examples assume the following has been set up:

  • The domain config.xml file references two diagnostic system modules that are part of the domain configuration, as follows: 

    <wldf-system-resource>
  <name>Module-0</name>
  <descriptor-file-name>diagnostics/Module-0-3905.xml</descriptor-file-name>
  <description></description>
</wldf-system-resource>
<wldf-system-resource>
  <name>Module-1</name>
  <descriptor-file-name>diagnostics/Module-1-3904.xml</descriptor-file-name>
  <description></description>
</wldf-system-resource>

  • The server name shown in these examples is myserver.

  • The external descriptor file external-wldf.xml is located in the domain's root directory, wl_domain. It contains the following lines for configuring the diagnostic system module named External-1: 

<?xml version='1.0' encoding='UTF-8'?>
<wldf-resource xmlns="http://xmlns.oracle.com/weblogic/weblogic-diagnostics"
xmlns:sec="http://xmlns.oracle.com/weblogic/security"
xmlns:wls="http://xmlns.oracle.com/weblogic/security/wls"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.oracle.com/weblogic/weblogic-diagnostics
http://xmlns.oracle.com/weblogic/weblogic-diagnostics/2.0/weblogic-diagnostics.xsd">
  <name>External-1</name>
  <harvester>
    <enabled>true</enabled>
    <sample-period>10000</sample-period>
    <harvested-type>
      <name>weblogic.management.runtime.ServerRuntimeMBean</name>
      <harvested-attribute>OverallHealthState.ReasonCodeSummary</harvested-attribute>
      <harvested-attribute>OverallHealthState.State</harvested-attribute>
      <namespace>ServerRuntime</namespace>
    </harvested-type>
  </harvester>
</wldf-resource>

Step 1: List Diagnostic System Modules

The following WLST command, shown in bold, lists the diagnostic system modules that are currently configured: 

wls:/wl_domain/Server1> listSystemResourceControls()
External        Enabled              Name 
--------        -------              ------------------------------
false           false                Module-0
false           false                Module-1

The preceding command shows that Module-0 and Module-1 are configured in the domain (that is, they are referenced from config.xml and are not configured by external resource descriptors), but that they have not been activated.

Step 2: Activate Module-0

The following WLST command activates Module-0: 

wls:/mydomain/serverConfig> enableSystemResource('Module-0')

You can also supply a server name to all of the WLDF system resource runtime control functions. If you do not specify a server name, the enableSystemResource() command defaults to the server instance to which WLST is currently connected. (However, by default, all configured WLDF system resources are available for runtime control operations on all servers in the domain.) 

wls:/mydomain/serverConfig> enableSystemResource('Module-0', Server='myserver')

Step 3: Verify that Module-0 is Activated

The following WLST command shows that Module-0 is now activated: 

wls:/mydomain/serverConfig> listSystemResourceControls()
External        Enabled             Name 
--------        -------             ------------------------------
false           true                Module-0
false           false               Module-1

Step 4: Activate Module-1

The following WLST commands activate Module-1 and verify the activation state of all diagnostic system modules: 

wls:/mydomain/serverConfig> enableSystemResource('Module-1', Server='myserver')
wls:/mydomain/serverConfig> listSystemResourceControls()
External        Enabled             Name 
--------        -------             ------------------------------
false           true                Module-0
false           true                Module-1

Step 5: Deactivate Configured Diagnostic Modules

The following WLST commands deactivate all diagnostic system modules that are configured in the domain and verify their state:

wls:/mydomain/serverConfig> disableSystemResource('Module-0')
wls:/mydomain/serverConfig> disableSystemResource("Module-1")
wls:/mydomain/serverConfig> listSystemResourceControls()
External        Enabled              Name 
--------        -------              ------------------------------
false           false                Module-0
false           false                Module-1

Step 6: Create a Diagnostic System Module from an External Resource Descriptor File

The external resource descriptor needs to be accessible by the WLST client. The following WLST command creates and deploys the diagnostic system module External-1 from the external resource descriptor in the file external-wldf.xml, and verifies its activation state. () 

wls:/mydomain/serverConfig> createSystemResourceControl('external-wldf', 'external-wldf.xml')
wls:/mydomain/serverConfig> listSystemResourceControls()
External        Enabled              Name 
--------        -------              ------------------------------
false           false                Module-0
true            false                external-wldf
false           false                Module-1

Note that the External column identifies External-1 as being configured by an external resource descriptor.

Step 7: Activate External-1

Because the createSystemResourceControl() command only deploys the diagnostic system module, the following WLST command activates it. The subsequent command verifies the diagnostic system module's activation state. 

wls:/mydomain/serverConfig> enableSystemResource("external-wldf")
wls:/mydomain/serverConfig> listSystemResourceControls()
External        Enabled             Name 
--------        -------             ------------------------------
false           false               Module-0
true            true                external-wldf
false           false               Module-1

Step 8: Deactivate External-1

The following WLST commands deactivate External-1 and verify its deactivation status: 

wls:/mydomain/serverConfig> disableSystemResource("external-wldf")
wls:/mydomain/serverConfig> listSystemResourceControls()
External        Enabled              Name 
--------        -------              ------------------------------
false           false                Module-0
true            false                external-wldf
false           false                Module-1

Step 9: Destroy External-1

The following WLST command destroys the diagnostic system module that is configured by an external resource descriptor:

wls:/mydomain/serverConfig> destroySystemResourceControl("external-wldf")

Step 10: Verify Original State of Configured Diagnostic Modules

The following WLST command verifies that the domain's configuration is reverted to its original state, showing only the two diagnostic system modules whose configuration is persisted in the config.xml file: 

wls:/mydomain/serverConfig> listSystemResourceControls()
External        Enabled              Name 
--------        -------              ------------------------------
false           false                Module-0
false           false                Module-1

More Information About Configuring Diagnostic System Modules

See the following sections for detailed instructions about configuring WLDF system modules:

Parent topic: Configuring Diagnostic System Modules

Configuring Diagnostic Modules for Applications

WLDF supports the ability to configure instrumentation of an application by means of a diagnostic application module. A diagnostic application module is similar to a diagnostic system module, with the exception that you configure it in an XML descriptor file that you package with the application archive file. A diagnostic application module deployed this way is available only to the application in which that module is enclosed. This ensures that the application can be reliably deployed into new environments with access to all required resources in the diagnostic module.

You configure and deploy application-scoped instrumentation as a diagnostic module, which is similar to a diagnostic system module. However, an application module is configured in an XML descriptor (configuration) file named weblogic-diagnostics.xml, which is packaged with the application archive in the ARCHIVE_PATH/META-INF directory for the deployed application. For example, C:\Oracle\Middleware\Oracle_Home\user_projects\applications\medrec\dist\standalone\exploded\medrec\META-INF\weblogic-diagnostics.xml.

Note:

The DyeInjection monitor, which is used to configure diagnostic context (a way of tracking requests as they flow through the system), can be configured only at the server level. But once a diagnostic context is created, the context attached to incoming requests remains with the requests as they flow through the application. For information about the diagnostic context, see Configuring the DyeInjection Monitor to Manage Diagnostic Contexts.

For more information about configuring and deploying diagnostic modules for applications, see:

Parent topic: Understanding WLDF Configuration

WLDF Configuration MBeans and Their Mappings to XML Elements

The set of WLDF configuration MBeans, along with the diagnostic system module beans for WLDF objects, are organized into a specific hierarchy in a WebLogic domain.

Figure 5-2 shows the hierarchy of the WLDF configuration MBeans and the diagnostic system module beans for WLDF objects in a WebLogic Server domain.

Figure 5-2 WLDF Configuration Bean Tree

Description of Figure 5-2 follows
Description of "Figure 5-2 WLDF Configuration Bean Tree"

The following WLDF MBeans configure WLDF at the server level. They map to XML elements in the config.xml configuration file for a domain:

  • WLDFServerDiagnosticMBean controls configuration settings for the Data Archive and Diagnostic Images components for a server. It also controls whether diagnostic context for a diagnostic module is globally enabled or disabled. (Diagnostic context is a way to uniquely identify requests and track them as they flow through the system. See Configuring the DyeInjection Monitor to Manage Diagnostic Contexts.)

    This MBean is represented by a <server-diagnostic-config> child element of the <server> element in the config.xml file for the server's domain.

  • WLDFDataRetirementByAgeMBean specifies how data retirement for a WLDF archive is performed based on the age of records in that archive.

  • WLDFSystemResourceMBean contains the name of a descriptor file for a diagnostic module in the DOMAIN_HOME/config/diagnostics directory and the names of one or more the target servers on which that module is deployed.

    This MBean is represented by a <wldf-system-resource> element in the config.xml file for the domain.

    Note:

    You can create multiple diagnostic system modules in a domain. The configurations for the modules are saved in multiple descriptor files in the config/diagnostics directory for the domain. The domain's config.xml file, therefore, can contain the multiple <wldf-system-resource> elements that represent those modules.

  • WLDFResourceBean contains the configuration settings for a diagnostic system module. This bean is represented by a <wldf-resource> element in a DIAG_MODULE.xml diagnostics descriptor file in the domain's config/diagnostics directory. (See Figure 5-1 and Example 5-2.) The WLDFResourceBean contains configuration settings for the following components:

    • Harvester: The WLDFHarvesterBean is represented by the <harvester> element in a DIAG_MODULE.xml file.

    • Instrumentation: The WLDFInstrumentationBean is represented by the <instrumentation> element in a DIAG_MODULE.xml file.

    • Policies and Actions: The WLDFWatchNotificationBean is represented by the <watch-notification> element in a DIAG_MODULE.xml file.

    If a WLDFResourceBean is linked from a WLDFSystemResourceMBean, the settings for WLDF components apply to the targeted server. If a WLDFResourceBean is contained within a weblogic-diagnostics.xml descriptor file which is deployed as part of an application archive, you can configure only the Instrumentation component, and the settings apply only to that application. In the latter case, the WLDFResourceMBean is not a child of a WLDFSystemResourceMBean.

Parent topic: Understanding WLDF Configuration