Configuring and Using the WebLogic Diagnostic Framework
The WebLogic Diagnostic Framework (WLDF) provides features for generating, gathering, analyzing, and persisting diagnostic data from BEA WebLogic Server® instances and from applications deployed to server instances. For server-scoped diagnostics, some WLDF features are configured as part of the configuration for the 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 topics provide an overview of WLDF configuration:
For general information about WebLogic Server domain configuration, see Understanding Domain Configuration.
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 the XML file. When a configuration is changed by changing the values of MBean attributes, those changes are saved (persisted) in the XML files.
One characteristic of the relationship between MBeans and the XML files is that configuration MBean attributes map directly to configuration XML elements. For example, the Enable
attribute of the WLDFInstrumentationMBean
maps directly to the <enabled>
sub-element of <instrumentation>
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 directly edit an XML element in the configuration file, the value of the MBean attribute is updated when the MBean is instantiated.
For more information about WLDF Configuration MBeans, see About the Configuration MBean Hierarchy and 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.
As with other WebLogic Server subsystems, there are several ways to configure WLDF:
WLDF can be used to perform diagnostics tasks for server instances (and clusters) and for applications.
The following WLDF components are configured as part of the configuration for a server instance in a domain. The configuration is persisted in the domain's config.xml
file.
See Configuring Diagnostic Image Capture and Diagnostic Archives
The following WLDF components are configured as diagnostic modules, or resources, that can be deployed to server instances. These configuration settings are persisted in the diagnostic resource descriptor files (configuration files) that can be targeted to one or more server instances.
See Configuring Diagnostic System Modules.
Note: If you have configured diagnostic context for a server instance (which is configured as part of the instrumentation for a diagnostic module), you globally enable or disable that module's context in the domain's config.xml
file, not in the configuration for the module itself.
The WLDF Instrumentation component can be used with applications. The Instrumentation component is configured in a resource descriptor file deployed with the application in the applications archive file. See Configuring Diagnostic Modules for Applications.
The Diagnostic Image Capture component and the Diagnostic Archive component are configured in a domain's config.xml
file. They are configured in the <server-diagnostic-config>
element, which is a child of the a <server>
element in a domain, as shown in Listing 2-1.
Listing 2-1 Sample WLDF Configuration Information in the Config.xml File for a Domain
<domain>
<server>
<name>myserver</name><server-diagnostic-config>
</server>
<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>
<!-- 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 Listing 2-2. -->
</domain>
For more information, see the following:
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. System modules are globally available for targeting to servers and clusters configured in a domain.
A diagnostic system module 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://www.bea.com/ns/weblogic/90/diagnostics.xsd. See WebLogic Server Diagnostics Configuration Schema Reference for documentation.
When you create a diagnostic system module using the Administration Console or the WebLogic Scripting Tool (WLST), WebLogic Server creates it in the DOMAIN_NAME
/config/diagnostics
directory, and a reference to the module is added to the domain's config.xml
file.
Note: Even if you are writing your own XML configuration files, you may want to create a diagnostic module from the Console. That way, you can start with the valid XML that the Console creates. For information see Create diagnostic system modules in the Administration Console Online 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. The <wldf-system-resource>
element can also include a <diagnostic-context-enabled>
element to enable or disable diagnostic context for the target server instance(s) or cluster(s).
For example, Listing 2-2 shows a module named myDiagnosticModule
targeted to the server myserver
and another module named newDiagnosticMod
targeted to servers ManagedServer1
and ManagedServer1
. The diagnostic context is enabled for the newDiagnosticMod
module.
Listing 2-2 Sample WLDF Configuration Information in the Config.xml File for a Domain
<domain>
<!-- Other domain-level configuration elements -->
<wldf-system-resource
xmlns="
http://www.bea.com/ns/weblogic/90/diagnostics"
>
<name>myDiagnosticModule</name>
<target>myserver</target>
<descriptor-file-name>diagnostics/MyDiagosticModule.xml
<description>My diagnostic module</description>
</descriptor-file-name>
</wldf-system-resource>
<wldf-system-resource>
<name>newDiagnosticMod</name>
<target>ManagedServer1,ManagedServer2</target>
<descriptor-file-name>diagnostics/newDiagnosticMod.xml
</descriptor-file-name>
<diagnostic-context-enabled>true</diagnostic-context-enabled>
<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 2-1.
Figure 2-1 Relationship of config.xml to System Descriptor File
Except for the name and list of targets, which are listed in the config.xml
file, as described above, all configuration for a diagnostic module is saved in its resource descriptor file. Listing 2-3 shows portions of the descriptor file for a diagnostic module named myDiagnosticModule
.
Listing 2-3 Sample Diagnostics System Module Descriptor File, MyDiagnosticModule.xml
<wldf-resource xmlns="http://www.bea.com/ns/weblogic/90/diagnostics"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bea.com/ns/weblogic/90/diagnostics.xsd">
<name>
MyDiagnosticModule
</name>
<instrumentation>
<!-- Configuration elements for one or more diagnostic monitors -->
</instrumentation>
<harvester>
<!-- Configuration elements for harvesting metrics from one or more
MBean types, instances, and attributes -->
</harvester>
<watch-notification>
<!-- Configuration elements for one or more watches and one or more
</watch-notification>
notifications-->
</wldf-resource>
A diagnostic system module can be targeted to zero, one, or more servers, although a server can have only one module targeted to it at a time. You can create multiple modules that monitor different aspects of your system. Then, you can 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. That capability provides considerable flexibility in writing and using diagnostic monitors that address a specific diagnostic goal, without interfering with the operation of the server instances themselves.
See the following sections for detailed instructions for configuring WLDF system resources:
Application-scoped instrumentation is configured and deployed as a diagnostic module, which is similar to a diagnostic system module. However, an application module is configured in an XML configuration file named weblogic-diagnostics.xml
which is packaged with the application archive.
Notes: You can configure only the Instrumentation component in a diagnostic descriptor for an application.
The DyeInjection
monitor, which is used to configure diagnostic context, can be configured only at the server level. But once a diagnostic context is created, the context attached to incoming requests remain with the requests as they flow through the application.
For detailed instructions for configuring instrumentation for applications. see Configuring Application-scoped Instrumentation.
Figure 2-2 shows the hierarchy of the WLDF configuration MBeans and the diagnostic system module Beans for WLDF objects in a WebLogic domain.
Figure 2-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. This MBean is represented by a <server-diagnostic-config>
element in the config.xml
file for the domain.
WLDFSystemResourceMBean
contains the name of a descriptor file for a diagnostic module in the 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 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 module. This Bean is represented by a <wldf-resource>
element in a ModuleName
.xml
diagnostics descriptor file in the domain's config/diagnostics
directory. The WLDFResourceBean
contains configuration settings for the following components:WLDFHarvesterBean
is represented by the <harvester>
element in a ModuleName
.xml
file.WLDFInstrumentationBean
is represented by the <instrumentation>
element in a ModuleName
.xml
file.WLDFWatchNotificationBean
is represented by the <watch-notification>
element in a ModuleName
.xml
file.For an application, if a WLDFResourceBean
is linked from a WLDFSystemResourceBean
, the settings for WLDF components apply to the targeted server and to any applications running on that 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 WLDFResourceBean
is not a child of a WLDFSystemResourceBean
.