Configuring and Using the WebLogic Diagnostics Framework

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Configuring Instrumentation

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:

 


Concepts and Terminology

This section introduces instrumentation concepts and terminology.

Instrumentation Scope

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.

Configuration and Deployment

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 in the ARCHIVE_PATH/META-INF directory for the deployed application.

Joinpoints, Pointcuts, and Diagnostic Locations

Instrumentation code is inserted into (or “woven” into) server and application code at precise locations. The following terms are used to describe these locations:

Note: You cannot use WLDF diagnostic monitors with classes that have AspectJ aspects woven into the code.

Diagnostic Monitor Types

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, Servlet_Around_Service is an application-scoped delegating monitor, which can be used to trigger diagnostic actions at the entry to and at the exit of certain servlet and JSP methods.

There are three types of instrumentation diagnostic monitors:

Table 10-1 summarizes the differences among the types of monitors.

Table 10-1 Diagnostic Monitor Types
Monitor Type
Scope
Pointcut
Location
Action
Standard monitor
Server
Fixed
Fixed
Fixed
Delegating monitor
Server or Application
Fixed
Fixed
Configurable
Custom monitor
Application
Configurable
Configurable
Configurable

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 DyeInjection Monitor to Manage Diagnostic Contexts.

Diagnostic Actions

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 of the DIAG_MODULE.xml configuration file:

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.

 


Instrumentation Configuration Files

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:

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.

 


XML Elements Used for Instrumentation

This section provides descriptor fragments and tables that summarize information about the XML elements used to configure instrumentation and the instrumentation diagnostic monitors.

<Instrumentation> XML Elements

Table 10-2 describes the <instrumentation> elements in the DIAG_MODULE.xml file. The following configuration fragment illustrates the use of those elements:

<wldf-resource>
  <name>MyDiagnosticModule</name>
<instrumentation>
   <enabled>true</enabled>
   <!-- The following <include> element would apply only to an
        application-scoped Instrumentation descriptor -->
   <include>foo.bar.com.*</include>
   <!-- &lt;wldf-instrumentation-monitor&gt; elements to define diagnostic
        monitors for this diagnostic module -->
</instrumentation>
<!-- Other elements to configure this diagnostic module -->
</wldf-resource>

Table 10-2 <instrumentation> XML Elements in the DIAG_MODULE.xml Configuration File
Element
Description
<instrumentation>
The element that begins an instrumentation configuration.
<enabled>
If true, instrumentation is enabled. If false, no instrumented code will be inserted in classes in this instrumentation scope, and all diagnostic monitors within this scope are disabled. The default value is false.
You must enable instrumentation at the server level to enable instrumentation for the server and for any applications deployed to it. You must further enable instrumentation at the application level to enable instrumentation for the application (that is, in addition to enabling the server-scoped instrumentation).
<include>
An optional element specifying the list of classes where instrumented code can be inserted. Wildcards (*) are supported. You can specify multiple <include> elements. If specified, a class must satisfy an <include> pattern for it to be instrumented.
Applies only to application-scoped instrumentation. Any specified <include> or <exclude> patterns are applied to the application scope as a whole.

Note: You can also specify <include> and <exclude> patterns for specific diagnostic monitors. See the entries for <include> and <exclude> in Table 10-3

As classes are loaded, they must pass an include/exclude pattern check before any instrumentation code is inserted. Even if a class passes the include/exclude pattern checks, whether or not it is instrumented depends on the diagnostic monitors included in the configuration descriptor. An application-scoped delegating monitor from the library has its own predefined classes and pointcuts. A custom monitor specifies its own pointcut expression. Therefore a class can pass the include/exclude checks and still not be instrumented.

Note: Instrumentation is inserted in applications at class load time. A large application that is loaded often may benefit from a judicious use of <include> and/or <exclude> elements. You can probably ignore these elements for small applications or for medium-to-large applications that are loaded infrequently.

<exclude>
An optional element specifying the list of classes where instrumented code cannot be inserted. Wildcards (*) are supported. You can specify multiple <exclude> elements. If specified, classes satisfying an <exclude> pattern are not instrumented.
Applies only to application-scoped instrumentation. See the <include> description, above.

<wldf-instrumentation-monitor> XML Elements

Diagnostic monitors are defined in <wldf-instrumentation-monitor> elements, which are children of the <instrumentation> element in a DIAG_MODULE.xml descriptor for server-scoped instrumentation or the META-INF/weblogic-diagnostics.xml descriptor for application-scoped instrumentation.

The following fragment shows the configuration for a delegating monitor and a custom monitor in an application. (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 DyeInjection Monitor to Manage Diagnostic Contexts, for information about configuring the DyeInjection monitor.

Table 10-3 describes the <wldf-instrumentation-monitor> elements.

Table 10-3 <wldf-instrumentation-monitor> XML Elements in the DIAG_MODULE.xml or weblogic-diagnostics.xml file
Element
Description
<wldf-instrumentation-monitor>
The element that begins a diagnostic monitor configuration.
<enabled>
If true, the monitor is enabled. If false, the monitor is disabled. You enable or disable each monitor separately. The default value is true.
<name>
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. The name for a custom monitor must be unique; that is, it cannot duplicate the name of any monitor in the library.
<description>
An optional element describing the monitor.
<action>
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 <action> elements. An action must be compatible with the monitor type. For the list of predefined actions for use by delegating and custom monitors, see WLDF Instrumentation Library.
<dye-filtering-enabled>
An optional element. If true, dye filtering is enabled for the monitor. If false, dye-filtering is disabled. If dye filtering is not enabled at the server level, enabling dye filtering for a monitor for will have no effect. The default value is false.
<dye-mask>
An optional element. If dye filtering is enabled, the dye mask, when compared with the values in the diagnostic context, determines whether actions are taken. See Configuring the DyeInjection Monitor to Manage Diagnostic Contexts, for information about dyes and dye filtering.
<properties>
An optional element. Sets name=value pairs for dye flags.
Currently applies only to the DyeInjection monitor.
<location-type>
An optional element, whose value is one of before, after, or around. The location type determines when an action is triggered at a pointcut: before the pointcut, after the pointcut, or both before and after the pointcut.
Applies only to custom monitors; standard and delegating monitors have predefined location types. A custom monitor must define a location type and a pointcut.
<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.
Pointcut syntax is documented in Defining Pointcuts for Custom Monitors
<include>
An optional element specifying the list of classes where instrumented code can be inserted. Wildcards (*) are supported. You can specify multiple <include> elements. If specified, a class must satisfy an <include> pattern for it to be instrumented.
Applies only to application-scoped instrumentation. Any specified <include> or <exclude> patterns are applied only to the monitor defined in the parent <wldf-instrumentation-monitor> element.

Note: You can also specify <include> and <exclude> patterns for an entire instrumented application scope. See the entries for <include> and <exclude> in Table 10-2.

As classes are loaded, they must pass an include/exclude pattern check before any instrumentation code is inserted. Even if a class passes the include/exclude pattern checks, whether or not it is instrumented depends on the diagnostic monitors included in the configuration descriptor. An application-scoped delegating monitor from the library has its own predefined classes and pointcuts. A custom monitor specifies its own pointcut expression. Therefore a class can pass the include/exclude checks and still not be instrumented.

Note: Instrumentation is inserted in applications at class load time. A large application that is loaded often may benefit from a judicious use of <include> and/or <exclude> elements. You can probably ignore these elements for small applications or for medium-to-large applications that are loaded infrequently.

<exclude>
An optional element specifying the list of classes where instrumented code cannot be inserted. Wildcards (*) are supported. You can specify multiple <exclude> elements. If specified, classes satisfying an <exclude> pattern are not instrumented.
Applies only to diagnostic monitors in application-scoped instrumentation. See the <include> description, above.

Additional information on <dye-filtering-enabled> and <dye-mask> follows:

Thus, the dye filtering mechanism allows monitors to take diagnostic actions only for specific requests, without slowing down other requests. See Configuring the DyeInjection Monitor to Manage Diagnostic Contexts, for detailed information on diagnostic contexts and dye vectors.

Mapping <wldf-instrumentation-monitor> XML Elements to Monitor Types

Table 10-4 summarizes which <wldf-instrumentation-monitor> elements apply to which monitors.

Table 10-4 Mapping Instrumentation XML Elements to Monitor Types
Element
Standard
Delegating
Custom
<wldf-instrumentation-monitor>
X
X
X
<name>
X
X
X
<description>
X
X
X
<enabled>
X
X
X
<action>
 
X
X
<dye-filtering-enabled>
 
X
X
<dye-mask>
 
X
X
<properties>
X1
   
<location-type>
   
X
<pointcut>
   
X

1Currently used only by the DyeInjection monitor to set name=value pairs for dye flags.

 


Configuring Server-Scoped Instrumentation

To enable instrumentation at the server level, and to configure server-scoped monitors, perform the following steps:

  1. Decide how many WLDF system resources you want to create.
  2. You can have multiple DIAG_MODULE.xml 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.

  3. Decide which server-scoped monitors you want to include in a configuration:
    • If you plan to use dye filtering on a server, or on any deployed on that server, configure the DyeInjection monitor.
    • If you plan to use one or more of the server-scoped delegating monitors, decide which monitors to use and which actions to associate with each monitor.
  4. Create and configure the configuration file(s).
    • If you use the Administration Console to create the DIAG_MODULE.xml file (recommended), for delegating monitors, the console displays only actions that are compatible with the monitor. If you create a configuration file with an editor or with the WebLogic Scripting Tool (WLST), you must correctly match actions to monitors.
    • See the “Domain Configuration Files” in Understanding Domain Configuration for information about configuring the config.xml file.
  5. Validate and deploy the descriptor file. For server-scoped instrumentation, you can add and remove monitors and enable or disable monitors while the server is running.

Listing 10-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 10-1 Sample Server-Scoped Instrumentation (in DIAG_MODULE.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">
  <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>

 


Configuring Application-Scoped Instrumentation

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:

Comparing System-Scoped to Application-Scoped Instrumentation

Instrumenting an application is similar to instrumenting at the system level, but with the following differences:

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 also create your own custom monitors; however, the diagnostic actions that you attach to these monitors must be taken from the WLDF Instrumentation Library.

Table 10-5 compares the function and scope of system and application modules.

Table 10-5 Comparing System and Application Modules
Module Type
Add/Remove Objects Dynamically
Add/Remove Objects with Console
Modify with JMX Remotely
Modify with JSR-88 (non-remote)
Modify with Console
System Module
Yes
Yes
Yes
No
Yes - via JMX
Application Module
Yes, when hot-swap is enabled
No, when hot-swap is not enabled: module must be redeployed
Yes
No
Yes
Yes - via plan

Overview of the Steps Required to Instrument an Application

To implement a diagnostic monitor for an application, perform the following steps:

  1. Make sure that instrumentation is enabled on the server. See Configuring Server-Scoped Instrumentation.
  2. Create a well formed META-INF/weblogic-diagnostics.xml descriptor file for the application:
  3. Put the descriptor file in the application archive.
  4. Deploy the application. See Deploying WLDF Application Modules..

Creating a Descriptor File for a Delegating Monitor

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

Creating a Descriptor File for a Custom Monitor

The following is an example of a well-formed META-INF/weblogic-diagnostics.xml file for a custom monitor.

Listing 10-2 Sample Custom Monitor Configuration (in DIAG_MODULE.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">
 <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 TraceAction action will be invoked before (<location-type>before</location-type) any methods defined by the pointcut expression is invoked. Table 10-6 shows how the pointcut expression from Listing 10-2 is parsed. (Note the use of wildcards.)

Table 10-6 Description of a Sample Pointcut Expression
Pointcut Expression
Description
call( * com.foo.bar.* get* (...))
call( ): Trigger any defined actions when the methods whose jointpoints are defined by the remainder of this pointcut expression are invoked.
call( * com.foo.bar.* get* (...))
*: Return value. The wildcard indicates that the methods can have any type of return value.
call( * com.foo.bar.* get* (...))
com.foo.bar.*: Methods from class com.foo.bar and its subpackages are eligible.
call( * com.foo.bar.* get* (...))
get*: Any methods whose name starts with the string get is eligible.
call( * com.foo.bar.* get* (...))
(...): The ellipsis indicates that the methods can have any number of arguments.

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 these methods, and, just before 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.

Defining Pointcuts for Custom Monitors

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 you define expressions for pointcuts using the following pointcut syntax.

You can specify two types of pointcuts for custom monitors:

The syntax for defining a pointcut expression is as follows:

<pointcut> ::= [(] <joinpoint> [ <conditional> <joinpoint> ] [)]
<joinpoint> ::= [(] <execution-joinpoint> | <call-joinpoint>
<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> | <elipsis>
<class-type> ::= [<use-class-hierarchy>] ?    <class-or-interface-name-pattern>
<conditional> ::= AND [NOT] | OR [NOT] | NOT
<use-class-hierarchy> ::= '+'
<elipsis> ::= '...'

The following rules apply:

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>

  Back to Top       Previous  Next