Configuring and Using the WebLogic Diagnostic Framework
The Instrumentation component of the WebLogic Diagnostic Framework (WLDF) provides a mechanism for adding diagnostic code to BEA WebLogic Server® instances and the applications running on them. The key features provided by WLDF Instrumentation are:
WLDF provides a library of predefined diagnostic monitors and actions. You can also create application-scoped custom monitors, where you control the locations where diagnostic code is inserted in the application.
Instrumentation is described in the following sections:
This section introduces instrumentation concepts and terminology.
You can provide instrumentation services at the system level (servers and clusters) and at the application level. Many concepts, services, configuration options, and implementation features are the same for both. However, there are differences, and they are discussed throughout this documentation. The term "server-scoped instrumentation" refers to instrumentation configuration and features specific to WebLogic Server instances and clusters. "Application-scoped instrumentation" refers to configuration and features specific to applications deployed on WebLogic servers. The scope is built in to each monitor; you cannot modify a monitor's scope.
Server-scoped instrumentation for a server or cluster is configured and deployed as part of a diagnostic module, an XML configuration file located in the DOMAIN_NAME
/config/diagnostics
directory, and linked from config.xml
.
Application-scoped instrumentation is also configured and deployed as a diagnostics module, in this case an XML configuration file named weblogic-diagnostics.xml
which is packaged with the application archive.
Instrumenting code is inserted into server and application code at precise locations. The following terms are used to describe these locations:
<pointcut>
. Pointcuts are described in Defining Pointcuts for Custom Monitors.<location-type>
.A diagnostic monitor is categorized by its scope and its type. The scope is either server-scoped or application-scoped. The type is determined by the monitor's pointcut, diagnostic location, and actions. For example, Connector_After_Inbound
is an application-scoped delegating monitor, which can be used to trigger diagnostic actions at the exit of (that is, after) any method that handles inbound connections.
There are three types of instrumentation diagnostic monitors:
In the current release, the only standard monitor is the DyeInjection
monitor, which is a server-scoped monitor used to configure diagnostic context and dye injection at the server level. For more information, see Configuring the Diagnostic Context.
A delegating monitor by itself is incomplete. In order for a delegating monitor to perform any useful work, you must assign at least one action to the monitor.
Not all actions are compatible with all monitors. When you configure a delegating monitor from the Administration Console, you can choose only those actions that are appropriate for the selected monitor. If you are using WLST or editing a descriptor file by hand, you must make sure that the actions are compatible with the monitors. Validation is performed when the XML file is loaded at deployment time.
See WLDF Instrumentation Library. for a list of the delegating monitors and actions provided by the WLDF Instrumentation Library.
Table 9-1 summarizes the differences among the types of monitors.
Diagnostic actions execute diagnostic code that is appropriate for the associated delegating or custom monitor (standard monitors have predefined actions). In order for a delegating or custom monitor to perform any useful work, you must configure at least one action for the monitor.
The WLDF diagnostics library provides the following actions, which you can attach to a monitor by including the action's name in an <action>
element when configuring the monitor:
Actions must be correctly matched with monitors. For example, the TraceElapsedTime
action is compatible with a delegating or custom monitor whose diagnostic location type is around
. See WLDF Instrumentation Library. for more information.
You can restrict when a diagnostic action is triggered by setting a dye mask on a monitor. This mask determines which dye flags in the diagnostic context trigger actions. See <wldf-instrumentation-monitor> XML Elements for information on setting a dye mask for a monitor.
Note: Diagnostic context, dye injection, and dye filtering are described in Configuring the Diagnostic Context.
This section provides information on the following topics:
Instrumentation is configured as part of a diagnostics descriptor, an XML configuration file, whose name and location depend on whether you are implementing system-level (server-scoped) or application-level (application-scoped) instrumentation:
DOMAIN_NAME
/config/diagnostics
This directory can contain multiple diagnostic descriptor files. Filenames are arbitrary but must be terminated with.xml
(myDiag.xml
is a valid filename). Each file can contain configuration information for one or more of the deployable diagnostic components: Harvester, Instrumentation, or Watch and Notification. An <instrumentation>
section in a descriptor file can configure one or more diagnostic monitors. Server-scoped instrumentation can be enabled, disabled, and in most cases reconfigured without restarting the server.
Only one system-level diagnostics descriptor file can be active at a time for a server (or cluster). The active file is linked and targeted from the following configuration file:
DOMAIN_NAME
/config/config.xml
See Understanding Domain Configuration for general information about the creation, content, and parsing of configuration files.
META-INF/weblogic-diagnostics.xml
Because instrumentation is the only diagnostics component that is deployable to applications, this file can contain only instrumentation configuration information. Application-scoped instrumentation can be enabled and disabled without redeploying the application.You can also use JSR-88 deployment plans to enable or disable a monitor, or to modify the actions associated with a monitor.
Note that for instrumentation to be available for an application, instrumentation must be enabled on the server to which the application is deployed.
The diagnostics XML schema is located at:
http://www.bea.com/ns/weblogic/90/diagnostics.xsd
See WebLogic Server Diagnostics Configuration Schema Reference for documentation.
Each diagnostics descriptor file must begin with the following lines:
<wldf-resource xmlns="http://www.bea.com/ns/weblogic/90/diagnostics"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
For an overview of WLDF resource configuration, see Understanding WLDF Configuration.
This section provides descriptor fragments and tables that summarize information about the XML elements used to configure instrumentation and the instrumentation diagnostic monitors.
<instrumentation>
element.<wldf-instrumentation-monitor>
element.Table 9-2 describes the <instrumentation>
elements. The following configuration fragment illustrates the use of those elements:
<instrumentation>
<enabled>true</enabled>
<!-- The following <include> element would apply
only to an appplication-scoped monitor -->
<include>foo.bar.com.*</include>
</instrumentation>
Table 9-3 describes the <wldf-instrumentation-monitor>
elements. The following configuration fragment illustrates the use of those elements. The fragment configures an application-scoped delegating monitor and a custom monitor. You could modify this fragment for server-scoped instrumentation by replacing the application-scoped monitors with server-scoped monitors.
<instrumentation>
<enabled>true</enabled>
<wldf-instrumentation-monitor>
<name>Servlet_Before_Service</name>
<enabled>true</enabled>
<dye-mask>USER1</dye-mask>
<dye-filtering-enabled>true</dye-filtering-enabled>
<action>TraceAction</action>
</wldf-instrumentation-monitor>
<wldf-instrumentation-monitor>
<name>MyCustomMonitor</name>
<enabled>true</enabled>
<action>TraceAction</action>
<location-type>before</location-type>
<pointcut>call( * com.foo.bar.* get*(...));</pointcut>
</wldf-instrumentation-monitor>
</instrumentation>
Note that the Servlet_Before_Service
monitor sets a dye mask and enables dye filtering. This will be useful only if instrumentation is enabled at the server level and the DyeInjection
monitor is enabled and properly configured. See Configuring the Diagnostic Context, for information about configuring the DyeInjection
monitor.
If |
|
The name of the monitor. For standard and delegating monitors, use the names of the predefined monitors in WLDF Instrumentation Library. For custom monitors, an arbitrary string that identifies the monitor. |
|
An optional element, which applies to delegating and custom monitors. If you do not specify at least one action, the monitor will not generate any information. You can specify multiple |
|
An optional element. If |
|
An optional element. If dye filtering is enabled, the dye mask determines whether actions are taken. See Configuring the Diagnostic Context, for information about dyes and dye filtering. |
|
An optional element. Sets Applies only to the |
|
An optional element, whose value is one of Applies only to custom monitors; standard and delegating monitors have predefined location types. A custom monitor must define a location type and a pointcut. |
|
An optional element. A pointcut element contains an expression that defines joinpoints where diagnostic code will be inserted. Applies only to custom monitors; standard and delegating monitors have predefined pointcuts. A custom monitor must define a location type and a pointcut. |
Additional information on <dye-filtering-enabled>
and <dye-mask>
follows:
DyeInjection
monitor is enabled and configured for a server or a cluster, you can use dye filtering in downstream delegating and custom monitors to inspect the dyes injected into a request's diagnostic context by that DyeInjection
monitor.DyeInjection
monitor determines which bits are set in the 64-bit dye vector associated with a diagnostic context. When the <dye-filtering-enabled>
attribute is enabled for a monitor, its diagnostic activity is suppressed if the dye vector in a request's diagnostic context does not match the monitor's configured dye mask. If the dye vector matches the dye mask (a bitwise AND
), the application can execute its diagnostic actions:
(dye_vector & dye_mask == dye_mask)
Thus, the dye filtering mechanism, allows monitors to take diagnostic actions only for specific requests, without slowing down other requests. See Configuring the Diagnostic Context, for detailed information on diagnostic contexts and dye vectors.
Table 9-4 summarizes which <wldf-instrumentation-monitor>
elements apply to which monitors.
X1 |
|||
DyeInjection
monitor to set name=value
pairs for dye flags.
To enable instrumentation at the server level, and to configure server-scoped monitors, perform the following steps:
You can have multiple diagnostic descriptor files in a domain, but for each server (or cluster) you can deploy only one diagnostic descriptor file at a time. One reason for creating more than one file is to give yourself flexibility. You could have, for example, five diagnostic descriptor files in the
DOMAIN_NAME
/config/diagnostics
directory. Each file contains a different instrumentation (and perhaps harvester and watch and notification) configuration. You then deploy a file to a server based on which monitors you want active for specific situations.
DyeInjection
monitor.Listing 9-1 contains a sample server-scoped instrumentation configuration file which enables instrumentation, and configures the DyeInjection
standard monitor and the Connector_Before_Work
delegating monitor. A single <instrumentation>
element contains all instrumentation configuration for the module. Each diagnostic monitor is defined in a separate <wldf-instrumentation-monitor>
element.
Listing 9-1 A Sample Server-scope Instrumentation Descriptor File
<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">
<instrumentation>
<enabled>true</enabled>
<wldf-instrumentation-monitor>
<name>DyeInjection</name>
<description>Inject USER1 and ADDR1 dyes
</description>
<enabled>true</enabled>
<properties>USER1=weblogic
ADDR1=127.0.0.1</properties>
</wldf-instrumentation-monitor>
<wldf-instrumentation-monitor>
<name>Connector_Before_Work</name>
<enabled>true</enabled>
<action>TraceAction</action>
<dye-filtering-enabled>true</dye-filtering-enabled>
<dye-mask>USER1</dye-mask>
</wldf-instrumentation-monitor>
</instrumentation>
</wldf-resource>
At the application level, WLDF instrumentation is configured as a deployable module, which is then deployed as part of the application.
The following sections provide information you need to configure application-scoped instrumentation:
Instrumenting an application is similar to instrumenting at the system level, but with the following differences:
DyeInjection
, is server-scoped.weblogic-diagnostics.xml
descriptor file. You create a META-INF/weblogic-diagnostics.xml
file, configure instrumentation, and put the file in the application's archive. When the archive is deployed, instrumentation is automatically inserted when the application is loaded.<wldf-instrumentation-monitor>
). However, to remove a monitor from an application, you must redeploy the application. (You can dynamically disable a monitor, but the monitor remains embedded in the application's code until the application is redeployed.)The XML descriptors for application-scoped instrumentation are defined in the same way as for server-scoped instrumentation. You can configure instrumentation for an application solely by using the delegating monitors and diagnostic actions available in the WLDF Instrumentation Library. You can create your own custom monitors; however, the diagnostic actions that you attach to these monitors must be taken from the Instrumentation Library.
To implement a diagnostic monitor for an application, perform the following steps:
META-INF/weblogic-diagnostics.xml
descriptor file for the application:<instrumentation>
element: <enabled>true</enabled>
See Creating a Descriptor File for a Delegating Monitor and Creating a Descriptor File for a Custom Monitor for samples of well-formed descriptor files.
See Defining Pointcuts for Custom Monitors for information on creating a pointcut expression.
The following is an example of a well-formed META-INF/weblogic-diagnostics.xml
file for an application-scoped delegating monitor:
<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">
<instrumentation>
<enabled>true</enabled>
<wldf-instrumentation-monitor>
<name>Servlet_Before_Service</name>
<enabled>true</enabled>
<dye-mask>USER1</dye-mask>
<dye-filtering-enabled>true</dye-filtering-enabled>
<action>TraceAction</action>
</wldf-instrumentation-monitor>
</instrumentation>
</wldf-resource>
The Servlet_Before_Service
monitor is an application-scoped monitor selected from the WLDF monitor library. It is hardcoded with a pointcut that sets joinpoints at method entry for several servlet/jsp methods. Because the application enables dye filtering and sets the USER1
flag in its dye mask, the TraceAction
action will be invoked only when the dye vector in the diagnostic context passed to the application also has its USER1
flag set. (The dye vector is set at the system level via the DyeInjection
monitor.) Therefore, the Servlet_Before_Service
monitor in this application is essentially quiescent until it inspects a dye vector and finds the USER1
flag set. This filtering reduces the amount of diagnostic data generated, and ensures that the generated data is of interest to the administrator.
The following is an example of a well-formed META-INF/weblogic-diagnostics.xml
file for a custom monitor:
<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">
<instrumentation>
<enabled>true</enabled>
<wldf-instrumentation-monitor>
<name>MyCustomMonitor</name>
<enabled>true</enabled>
<action>TraceAction</action>
<location-type>before</location-type>
<pointcut>call( * com.foo.bar.* get* (...));</pointcut>
</wldf-instrumentation-monitor>
</instrumentation>
</wldf-resource>
The <name>
for a custom monitor is an arbitrary string chosen by the developer. Because this monitor is custom, it has no predefined locations when actions should be invoked; the descriptor file must define the location type and pointcut expression. In this example, the TraceActionc
action will be invoked before (<location-type>before</location-type
) any methods defined by the pointcut expression is invoked. The example's pointcut expression is parsed as follows (note the use of wildcards):
Therefore, this pointcut expression matches all get*()
methods in all classes in package com.foo.bar
and its subpackages. The methods can return values of any type, including void
, and can have any number of arguments of any type. Instrumentation code will be inserted before of these methods, and, just before of those methods are called, the TraceAction
action will be invoked.
See Defining Pointcuts for Custom Monitors
for a description of the grammar used to define pointcuts.
Custom monitors provide more flexibility than delegating monitors because you create pointcut expressions to control where diagnostics actions are invoked. As with delegating monitors, you must select actions from the action library.
A joinpoint is specific, well-defined location in a program. A pointcut is an expression that specifies a set of joinpoints. This section describes how expressions for pointcuts are defined using a subset of the AspectJ pointcut syntax.
You can specify two types of pointcuts for custom monitors:
The informal grammar is as follows:
<pointcut> ::= <execution-pointcut> | <callsite-pointcut>
<execution-pointcut> ::=execution
( <access-type> <joinpoint-signature> )
<callsite-pointcut> ::=call
( <joinpoint-signature> )
<joinpoint-signature> ::= <method-signature>
<method-signature> ::= <return-type> <class-type>.<method-name> ( <parameter-list> )
<return-type> ::= <class-type> | <primitive-type>
<parameter-list> ::= <parameter-type> (, <parameter-type>) *
<parameter-type> ::= <class-type> | <primitive-type> | <elepsis>
<class-type> ::= (<use-class-heirarchy>) ? <class-or-interface-name-pattern>
<use-class-heirarchy> ::= '+'
<elepsis> ::= '...'
*
) can be used in class types and method names. ...
) in the argument list signifies a variable number of arguments of any types beyond the argument. +
(plus sign) prefix to a class type identifies all subclasses, subinterfaces or concrete classes implementing the specified class/interface pattern. For example, the following pointcut matches method executions of all public initialized methods in all classes in package com.foo.bar
and its subpackages. The initialized methods may return values of any type, including void
, and may have any number of arguments of any types.
execution(public * com.foo.bar.* initialize(...))
The following pointcut matches the method calls (callsites) on all classes that directly or indirectly implement the com.foo.bar.MyInterface
interface (or a subclass, if it happens to be a class). The method names must start with get
, be public, and return an int
value. The method must accept exactly one argument of type java.lang.String
:
call(int +com.foo.bar.MyInterface get*(java.lang.String))
The following example shows how to use boolean operators to build a pointcut expression tree:
call(void com.foo.bar.* set*(java.lang.String)) OR
call( * com.foo.bar.* get*())
The following example illustrates how the previous expression tree would be rendered as a <pointcut>
element in a configuration file:
<pointcut>call(void com.foo.bar.* set*(java.lang.String)) OR
call( * com.foo.bar.* get*())</pointcut>
If an application is deployed with a well-formed META-INF/weblogic-diagnostics.xml
diagnostics descriptor file in place, the Instrumentation component automatically inserts diagnostic instrumentation code into matching application classes when the classes are loaded.
This descriptor may be specified inside an application ear
archive or a stand-alone module such as a war
, rar
or ejb
, and can be done for both exploded and unexploded archives.
Note: If an application ear
archive contains war
, rar
or ejb
modules that have the weblogic-diagnostics.xml
descriptors in their META-INF
directory, those descriptors will be ignored.
You can use any of the standard WebLogic Server tools provided for controlling deployment, including the WebLogic Administrative Console or the WebLogic Scripting Tool (WLST).
You can use the weblogic.PlanGenerator
tool to create an initial deployment plan, and interactively override specific properties of the weblogic-diagnostics.xml
descriptor. For example, to create the plan:
java weblogic.PlanGenerator -root c:\exportapps\myApplication
The PlanGenerator
tool inspects all J2EE deployment descriptors in the selected application, and creates a deployment plan with null variables for all relevant WebLogic Server deployment properties that configure external resources for the application.
For more information about creating and using deployment plans, see Configuring Applications for Production Deployment in Deploying Applications to WebLogic Server.
For more information about exporting an application's WebLogic Server deployment configuration to a custom deployment plan, including instructions for using PlanGenerator
, see Exporting an Application for Deployment to New Environments in Deploying Applications to WebLogic Server.
For dynamic control over diagnostic monitors in the application, the application must be deployed with a deployment plan. Again, the Administrator can use any of the standard WebLogic Server tools provided for controlling deployment, including the WebLogic Administrative Console or the WebLogic Scripting Tool (WLST). For example, the following WLST command deploys an application with a corresponding deployment plan.
wls:/mydomain/serverConfig> deploy('myApp', './myApp.ear', 'myserver',
'nostage', './plan.xml')
After deployment, the effective diagnostic monitor configuration is a combination of the original descriptor, combined with the overridden attribute values from the plan. Note that if the original descriptor did not include a monitor with the given name and the plan overrides an attribute of such a monitor, the monitor is added to the set of monitors to be used with the application. This way, if your application is built with an empty weblogic-diagnostics.xml
descriptor, you can add diagnostic monitors to the application during the deployment process, without having to modify the application archive.
Dynamic control of instrumentation monitors within applications is provided with the Deployment Plan (JSR-88) mechanism. With deployment plans, you can add diagnostic monitors into applications after they are built, without having to modify the application archives. The application must, however, include at least an empty weblogic-diagnostics.xml
descriptor for application instrumentation to work. With deployment plans, you can add monitors that are not present in the descriptor in the application archive. You can also update certain attributes of the monitors using deployment plans without having to restart the server or redeploy the application. For example, you can enable/disable diagnostic monitors or add/remove actions to monitors without redeploying the application.
Users can dynamically control monitors which are in use by the deployed application, by simply modifying the deployment plan and updating the application using the already identified tools. For example, you can enable/disable monitors and add/remove actions attached to them. You can also enable/disable dye-filtering and modify the dye mask for the monitor dynamically. Such changes take effect immediately without having to redeploy the application. For example, the following WLST command updates the application with a modified plan value:
wls:/mydomain/serverConfig> updateApplication('testapp',
'c:/tmp/plan.xml')