4 Understanding WLDF Configuration

The WebLogic Diagnostics Framework (WLDF) provides 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.

The following sections provide an overview of WLDF configuration:

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

Configuration MBeans and XML

As in other WebLogic Server subsystems, WLDF is configured using configuration MBeans (Managed Beans), and the configuration is persisted in 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 saved (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 With JMX for Oracle WebLogic Server.

Tools for Configuring WLDF

As with other WebLogic Server subsystems, there are several ways to configure WLDF:

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

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

  • Configure WLDF programmatically using JMX and the WLDF configuration MBeans. See Chapter 16, "Configuring and Using WLDF Programmatically," for specific information about programming WLDF. See Oracle WebLogic Server MBean Reference 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 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.

How WLDF Configuration Is Partitioned

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

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, or resources, 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)

  • Watch and Notification

  • Instrumentation

See Configuring Diagnostic System Modules.

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.

Configuring Diagnostic Image Capture and Diagnostic Archives

In the config.xml file for a domain, you configure the Diagnostic Image Capture component and the Diagnostic Archive component in the <server-diagnostic-config> element, which is a child of the <server> element in a domain, as shown in Example 4-1.

Example 4-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. 
       See Example 4-2. -->
</domain>

Note:

If WebLogic Server is configured with Oracle JRockit, and JRockit Flight Recorder is enabled, the diagnostic image capture can optionally include a JRockit Flight Recorder (JFR) file that includes WebLogic Server events. The JFR file can then be viewed in JRockit Mission Control.

For more information, see the following:

Configuring Diagnostic Image Capture for JRockit Flight Recorder

If WebLogic Server is configured with Oracle JRockit R28 or later, and JRockit Flight Recorder is not explicitly disabled, the JFR file is automatically included in the diagnostic image capture. The JFR file contains data from all event producers that are enabled. However, 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:

By default, the WLDF diagnostic volume is set to Low.

To include WebLogic Server event data in the JFR file:

  1. Ensure that WebLogic Server is configured with Oracle JRockit R28, which is available from the WebLogic Server installation program.

    For information, see Oracle WebLogic Server Installation Guide.

  2. Ensure that JFR flight recording is not disabled in JRockit.

    In a default installation of Oracle JRockit, Flight Recorder operates in Default Data Gathering Mode. No JRockit settings are required to have JVM events included in the JFR file.

    For information, see Oracle JRockit Flight Recorder Run Time Guide.

  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.

    For information, see "Configure WLDF diagnostic volume" in Oracle WebLogic Server Administration Console Help.

Note:

If the WLDF diagnostic volume is set to Off, and 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.

Configuring Diagnostic System Modules

To configure and use the Instrumentation, Harvester, and Watch and Notification 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. Keep in mind that:

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

  • At most, one diagnostic system module can be targeted to any given server or cluster.

The Diagnostic System Module and Its Resource Descriptor

You create a diagnostic system module through the Administration Console or the WebLogic Scripting Tool (WLST). It is created as a WLDFResourceBean, and the configuration is persisted in a resource descriptor file (configuration file), called DIAG_MODULE.xml, where DIAG_MODULE is the name of the diagnostic 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_NAME\config\diagnostics directory, where DOMAIN_NAME is the name of the domain's home directory. The file has the extension .xml.

Note:

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

For instructions on creating a diagnostic system module, see "Create diagnostic system modules" in the Oracle WebLogic Server Administration Console Help.

Referencing the Diagnostics System Module from Config.xml

When you create a diagnostic system module using the Administration Console or the WebLogic Scripting Tool (WLST), WebLogic Server creates it in DOMAIN_NAME/config/diagnostics, 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 Help.

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

For example, Example 4-2 shows a config.xml file with a module named myDiagnosticModule targeted to the server myserver and another module named newDiagnosticMod targeted to servers ManagedServer1 and ManagedServer2.

Example 4-2 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>ManagedServer1,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 4-1.

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

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

The DIAG_MODULE.xml Resource Descriptor Configuration

Except for the name and list of targets, which are listed in the config.xml file, as described above, all configuration for a diagnostic system module is saved in its resource descriptor file. Example 4-3 shows portions of the descriptor file for a diagnostic system module named myDiagnosticModule.

Example 4-3 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/1.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 watches and one or more 
         notifications-->
  </watch-notification>
</wldf-resource>

Managing Diagnostic System Modules

A diagnostic system module can be targeted to zero, one, or more servers or clusters, although a given server can have only one module targeted to it at a time. You can create multiple modules that monitor different aspects of your system. You can then choose which module 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 instance(s) 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.

More Information About Configuring Diagnostic System Resources

See the following sections for detailed instructions on configuring WLDF system resources:

Configuring Diagnostic Modules for Applications

You can configure only the Instrumentation component in a diagnostic descriptor for an application.

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, D:\bea\wlserver_10.3\samples\server\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 Chapter 12, "Configuring the DyeInjection Monitor to Manage Diagnostic Contexts."

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

WLDF Configuration MBeans and Their Mappings to XML Elements

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

Figure 4-2 WLDF Configuration Bean Tree

Description of Figure 4-2 follows
Description of "Figure 4-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 Chapter 12, "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.

  • WLDFSystemResourceMBean contains the name of a descriptor file for a diagnostic module in the DOMAIN_NAME/config/diagnostics directory and the name(s) of the target server(s) to 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. However, you can target only one diagnostic system module to a server at a time. You cannot have two files in the config/diagnostics directory whose active target is the same server.
  • 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 4-1 and Example 4-3.) 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.

    • Watch and Notification: 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.