Configuring and Using the WebLogic Diagnostics 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 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 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 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.
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.
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 applications archive file. See Configuring Diagnostic Modules for Applications.
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 Listing 3-1.
<!-- Other domain-based configuration elements, including references to
WLDF system resources, or diagnostic system modules.
See Listing 3-2. -->
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. System modules are globally available for targeting to servers and clusters configured in a domain.You may create multiple diagnostic system modules with distinct configurations. However, at most one diagnostic system module can be targeted to any given server or cluster.
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 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
\config\diagnostics directory, where
DOMAIN_NAME is the name of the domain's home directory. The file has the extension
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.
For instructions on creating a diagnostic system module, see Create diagnostic system modules in the Administration Console online help.
When you create a diagnostic system module using the Administration Console or the WebLogic Scripting Tool (WLST), WebLogic Server creates it in the
/config/diagnostics directory, and a reference to the module is added to the domain's
Note: It is recommended 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 information see Create diagnostic system modules in the Administration Console Online Help.
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, Listing 3-2 shows a module named
myDiagnosticModule targeted to the server
myserver and another module named
newDiagnosticMod targeted to servers
The relationship of the
config.xml file and the
MyDiagnosticModule.xml file is shown in Figure 3-1.
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. Listing 3-3 shows portions of the descriptor file for a diagnostic system module named
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.
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.
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
/META-INF directory for the deployed application (for example,
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.
Figure 3-2 shows the hierarchy of the WLDF configuration MBeans and the diagnostic system module beans for WLDF objects in a WebLogic Server domain.
WLDFServerDiagnosticMBeancontrols 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 means for uniquely identifying requests and tracking them as they flow through the system. See Configuring the DyeInjection Monitor to Manage Diagnostic Contexts.)
WLDFSystemResourceMBeancontains the name of a descriptor file for a diagnostic module in the
config/diagnosticsdirectory and the name(s) of the target server(s) to which that module is deployed.
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.
WLDFResourceBeancontains the configuration settings for a diagnostic system module. This bean is represented by a
<wldf-resource>element in a
.xmldiagnostics descriptor file in the domain's
config/diagnosticsdirectory. (See Figure 3-1 and Listing 3-3.) The
WLDFResourceBeancontains configuration settings for the following components:
WLDFHarvesterBeanis represented by the
<harvester>element in a
WLDFInstrumentationBeanis represented by the
<instrumentation>element in a
WLDFWatchNotificationBeanis represented by the
<watch-notification>element in 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