This chapter describes the Instrumentation component of the WebLogic Diagnostics Framework (WLDF) that provides a mechanism for adding diagnostic code to WebLogic Server instances and the applications running on them. The key features provided by WLDF Instrumentation are:
Diagnostic monitors. A diagnostic monitor is a dynamically manageable unit of diagnostic code that is inserted into server or application code at specific locations. You define monitors by scope (system or application) and type (standard, delegating, or custom).
Diagnostic actions. A diagnostic action is the action a monitor takes when it is triggered during program execution.
Diagnostic context. A diagnostic context is contextual information, such as unique request identifier and flags that indicate the presence of certain request properties such as originating IP address or user identity. The diagnostic context provides a means for tracking program execution and for controlling when monitors trigger their diagnostic actions. See Chapter 13, "Configuring the DyeInjection Monitor to Manage Diagnostic Contexts."
WLDF provides a library of predefined diagnostic monitors and actions. You can also create application-scoped custom monitors in which you control the locations in the application where diagnostic code is inserted.
This chapter includes the following sections:
This section introduces instrumentation concepts and terminology. The following topics are included:
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 levels. However, there are differences, which are discussed throughout this document. The term server-scoped instrumentation refers to instrumentation configuration and features specific to WebLogic Server instances and clusters. By contrast, application-scoped instrumentation refers to configuration and features specific to applications deployed on WebLogic Server instances. The scope is built in to each diagnostic 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_HOME/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.
Instrumentation code is inserted (or woven) into server and application code at precise locations. The following terms are used to describe these locations:
A joinpoint is a specific location in a class; for example, the entry point, or exit point, or both, of a method or a call site within a method.
A pointcut is an expression that specifies a set of joinpoints, for example all methods related to scheduling, starting, and executing work items. The XML element that specifies a pointcut is <pointcut>. Pointcuts are described in Defining Pointcuts for Custom Monitors.
A diagnostic location is the position relative to a joinpoint where the diagnostic activity will take place. Diagnostic locations are Before, After, and Around. The XML element that identifies a diagnostic location is <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, Servlet_Around_Service is an application-scoped delegating monitor that can be used to trigger diagnostic actions at the entry to and exit from specific servlet and JSP methods.
There are three types of diagnostic monitors:
A standard monitor performs specific, predefined diagnostic actions at specific, predefined pointcuts and locations. These actions, pointcuts, and locations are hard-coded in the monitor. You can enable or disable the monitor, but you cannot modify its behavior.
The only standard server-scoped monitor is the DyeInjection monitor, which you can use to create diagnostic context and to configure dye injection at the server level. For more information, see Chapter 13, "Configuring the DyeInjection Monitor to Manage Diagnostic Contexts."
The only standard application-scoped monitor is HttpSessionDebug, which you can use to inspect an HTTP Session object.
A delegating monitor has its scope, pointcuts, and locations hard-coded in the monitor, but you select the actions that the monitor performs. That is, the monitor delegates its actions to the ones you select. Delegating monitors are either server-scoped or application-scoped.
A delegating monitor by itself is incomplete. To have a delegating monitor perform useful work, you must assign at least one action to it.
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 configure a delegating monitor using WLST or by editing a descriptor file manually, you must make sure that the actions are compatible with that monitor. WLDF validates a delegating monitor when its XML configuration file is loaded at deployment time.
See Appendix B, "WLDF Instrumentation Library," for a list of the delegating monitors and actions provided by the WLDF Instrumentation Library.
A custom monitor is a special case of delegating monitor that:
Is available only for application-scoped instrumentation
Does not have a predefined pointcut or location
To configure a custom monitor, you assign it a name, define the pointcut and the diagnostics location that the monitor uses, and assign actions from the set of predefined diagnostic actions. The <pointcut> and <location type> elements are mandatory for a custom monitor.
Table 12-1 summarizes the differences among the types of monitors.
Table 12-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 the dye flags in the diagnostic context that trigger actions. See <wldf-instrumentation-monitor> XML Elements, for information about setting a dye mask for a monitor.
Note:
Diagnostic context, dye injection, and dye filtering are described in Chapter 13, "Configuring the DyeInjection Monitor to Manage Diagnostic Contexts."Diagnostic actions execute diagnostic code that is appropriate for the associated delegating or custom monitor (standard monitors have predefined actions). For a delegating or custom monitor to perform any useful work, you must configure at least one action for that 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:
DisplayArgumentsAction
MethodInvocationStatisticsAction
MethodMemoryAllocationStatisticsAction
StackDumpAction
ThreadDumpAction
TraceAction
TraceElapsedTimeAction
TraceMemoryAllocationAction
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 Appendix B, "WLDF Instrumentation Library," for more information.
Instrumentation is configured as part of a diagnostics descriptor, which is an XML configuration file whose name and location depend on whether you are implementing system-level (server-scoped) or application-level (application-scoped) instrumentation, as follows:
System-level instrumentation configuration is stored in one or more diagnostics descriptors in the following directory:
DOMAIN_HOME/config/diagnostics
This directory can contain multiple system-level diagnostic descriptor files. File names are arbitrary but must be terminated with .xml; for example, myDiag.xml. Each file can contain configuration information for one or more of the following deployable diagnostic components:
Harvester
Instrumentation
Watch and Notification
The configuration of one or more diagnostic monitors can be defined in an <instrumentation> section in the descriptor file. Server-scoped instrumentation can be enabled, disabled, and reconfigured without restarting the server.
Only one WLDF system resource (and hence one system-level diagnostics descriptor file) can be active for a server or cluster at any given time. The active descriptor is linked to and targeted from the following configuration file:
DOMAIN_HOME/config/config.xml
For more information about configuring diagnostic system modules, see Configuring Diagnostic System Modules. For general information about the creation, content, and parsing of configuration files in WebLogic Server, see Understanding Domain Configuration for Oracle WebLogic Server.
Application-level instrumentation configuration is packaged within an application's archive in the following location:
META-INF/weblogic-diagnostics.xml
Because instrumentation is the only diagnostics component that is deployable to applications, this descriptor can contain only instrumentation configuration information.
Note:
For instrumentation to be available for an application, instrumentation must be enabled on the server to which the application is deployed. (Server-scoped instrumentation is enabled and disabled in the <instrumentation> element of the diagnostics descriptor for the server.You can enable and disable diagnostic monitors without redeploying an application. However, you may need to redeploy the application after modifying other instrumentation features; for example, defining pointcuts or adding or removing monitors. Whether you need to redeploy depends on how you configure the instrumentation and how you deploy the application. There are three options:
Define and change the instrumentation configuration for the application directly, without using a JSR-88 deployment plan
Configure and deploy the application using a deployment plan that has placeholders for instrumentation settings
Enable the HotSwap feature when starting the server, and deploy using a deployment plan that has placeholders for instrumentation settings
For more information about these choices, see Using Deployment Plans to Dynamically Control Instrumentation Configuration.
For more information about deploying and modifying diagnostic application modules, see Chapter 15, "Deploying WLDF Application Modules."
The diagnostics XML schema is located at:
http://xmlns.oracle.com/weblogic/weblogic-diagnostics/1.0/weblogic-diagnostics.xsd
Each diagnostics descriptor file must begin with the following lines:
<wldf-resource xmlns="http://xmlns.oracle.com/weblogic/weblogic-diagnostics" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
For an overview of WLDF resource configuration, see Chapter 5, "Understanding WLDF Configuration."
This section provides descriptor fragments and tables that summarize information about the XML elements used to configure instrumentation and diagnostic monitors.
<Instrumentation> XML Elements, describes the top-level elements used within an <instrumentation> element.
<wldf-instrumentation-monitor> XML Elements, describes the elements used within a <wldf-instrumentation-monitor> element.
Mapping <wldf-instrumentation-monitor> XML Elements to Monitor Types, identifies the instrumentation elements that apply to each monitor.
Table 12-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>
<!-- <wldf-instrumentation-monitor> elements to define diagnostic
monitors for this diagnostic module -->
</instrumentation>
<!-- Other elements to configure this diagnostic module -->
</wldf-resource>
Table 12-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 is 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 12-1. 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> elements, <exclude> elements, or both. 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 preceding description of the <include> element. |
Diagnostic monitors are defined in <wldf-instrumentation-monitor> elements, which are children of the <instrumentation> element in the following descriptor:
The DIAG_MODULE.xml descriptor for server-scoped instrumentation
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 Chapter 13, "Configuring the DyeInjection Monitor to Manage Diagnostic Contexts," for information about configuring the DyeInjection monitor.
Table 12-3 describes the <wldf-instrumentation-monitor> elements.
Table 12-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 Appendix B, "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 Appendix B, "WLDF Instrumentation Library." |
|
<dye-filtering-enabled> |
An optional element. If true, dye filtering is enabled for the monitor. If false, dye-filtering is disabled. The default value is false. In order to use dye filtering, the DyeInjection monitor must be configured appropriately at the server level. |
|
<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 Chapter 13, "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 12-1. 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. |
Note the following additional information about the <dye-filtering-enabled> and <dye-mask> elements:
When a 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.
The configuration of the 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 Chapter 13, "Configuring the DyeInjection Monitor to Manage Diagnostic Contexts," for detailed information about diagnostic contexts and dye vectors.
Table 12-4 identifies the <wldf-instrumentation-monitor> elements that apply to each monitor type. An X indicates that an element applies to the corresponding monitor; N/A indicates that it does not.
Table 12-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> |
N/A |
X |
X |
|
<dye-filtering-enabled> |
N/A |
X |
X |
|
<dye-mask> |
N/A |
X |
X |
|
<properties> |
N/A |
N/A |
|
|
<location-type> |
N/A |
N/A |
X |
|
<pointcut> |
N/A |
N/A |
X |
Footnote 1 Currently used only by the 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:
Decide how many WLDF system resources you want to create.
You can have multiple DIAG_MODULE.xml diagnostic descriptor files in a domain. In addition, for each server or cluster in a domain, you can deploy multiple diagnostic descriptor files simultaneously. However, one reason for creating more than one file is for flexibility. For example, you could have five diagnostic descriptor files in the DOMAIN_HOME/config/diagnostics directory. Each file contains a different instrumentation (and perhaps Harvester and Watch and Notification) configuration. You then deploy the descriptor file that corresponds to the particular monitors you want active.
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 applications 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.
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 the 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 Oracle WebLogic Server for information about configuring config.xml.
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.
Example 12-1 contains a sample server-scoped instrumentation configuration file that 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.
Example 12-1 Sample Server-Scoped Instrumentation (in DIAG_MODULE.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">
<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:
Note:
Application classes and libraries that are put on the system classpath are not instrumented. Application class instrumentation works only on classes that are loaded by application classloaders. If application classes are put on the system classpath, either deliberately or inadvertently, they will be loaded by the system classloader. As a result no deployment time weaving is performed on those classes.Instrumenting an application is similar to instrumenting at the system level, but with the following differences:
Applications can use standard, delegating, and custom monitors.
The only server-scoped standard monitor is DyeInjection. The only application-scoped standard monitor is HttpSessionDebug. For more information, see the entry for HttpSessionDebug in Diagnostic Monitor Library.
Delegating monitors are either server-scoped or application-scoped. Applications must use the application-scoped delegating monitors.
All custom monitors are application-scoped.
The server's instrumentation settings affect the application. In order to enable instrumentation for an application, instrumentation must be enabled for the server on which the application is deployed. If server instrumentation is enabled at the time of deployment, instrumentation will be available for the application. If instrumentation is not enabled on the server at the time of deployment, enabling instrumentation in an application will have no effect.
Application instrumentation is configured with a weblogic-diagnostics.xml descriptor file. You create a META-INF/weblogic-diagnostics.xml file, configure the instrumentation, and put the file in the application's archive. When the archive is deployed, the instrumentation is automatically inserted when the application is loaded.
You can use a deployment plan to dynamically update configuration elements without redeploying the application. See Using Deployment Plans to Dynamically Control Instrumentation Configuration.
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 12-5 compares the function and scope of system and application diagnostic modules.
Table 12-5 Comparing System and Application Modules
| Module Type | Add or Remove Objects Dynamically | Add or Remove Objects with Console | Modify with JMX Remotely | Modify with JSR-88 (non-remote) | Modify with Console | Enable/Disable Dye Filtering and Dye Mask Dynamically |
|---|---|---|---|---|---|---|
|
System Module |
Yes |
Yes |
Yes |
No |
Yes (via JMX) |
Yes |
|
Application Module |
Yes, when HotSwap is enabled No, when HotSwap is not enabled: module must be redeployed |
Yes |
No |
Yes |
Yes (via plan) |
Yes |
Note:
As of WebLogic Server 10.3, you are not required to create aweblogic-diagnostics.xml file in the application's META-INF directory, as was the case in previous WebLogic Server releases. However, you can still use this method to initially configure diagnostic monitors for your application.To implement a diagnostic monitor for an application, perform the following steps:
Make sure that instrumentation is enabled on the server. See Configuring Server-Scoped Instrumentation.
Create a well formed META-INF/weblogic-diagnostics.xml descriptor file for the application. If you want to add any monitors that will be automatically enabled each time the application is deployed:
Enable the <instrumentation> element: <enabled>true</enabled>.
Add and enable at least one diagnostic monitor, with appropriate actions attached to it. (A monitor will generate diagnostic events only if the monitor is enabled and actions that generate events are attached to it.).
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 about creating a pointcut expression.
Put the descriptor file in the application archive.
Deploy the application. See Chapter 15, "Deploying WLDF Application Modules."
Keep the following points in mind:
The diagnostic monitors defined in weblogic-diagnostics.xml is listed on the Deployments: <server_name>: Configuration: Instrumentation page of the Administration Console.
If the META-INF/weblogic-diagnostics.xml descriptor in the application archive defines a monitor, it cannot be removed using the Administration Console. However, it can be disabled or enabled using the Administration Console.
You can add additional monitors from the Administration Console. Any monitors you add from the Administration Console will not be persisted to weblogic-diagnostics.xml; they will be saved in the application's deployment plan. Any monitors that were added in this way can be deleted using the Administration Console.
Application classes and libraries that are put on the server's classpath are not instrumented. Application class instrumentation works only on classes that are loaded by application classloaders.
If application classes are put on the system classpath, either deliberately or inadvertently, they will be loaded by the system classloader. As a result no deployment time weaving is performed on those classes.
The following example shows a well-formed META-INF/weblogic-diagnostics.xml descriptor file for an application-scoped delegating monitor. At a minimum, this file must contain the lines shown in bold. In this example, there is only one monitor defined (Servlet_Before_Service). However, you can define multiple monitors in the descriptor file.
<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"> <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 hard coded 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 as per the DyeInjection monitor configuration when the request enters the server. For example, if the DyeInjection monitor is configured with property USER1=weblogic and the request was originated by user weblogic, the USER1 dye flag in the dye vector will be set.
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. At a minimum, the file must contain the lines shown in bold.
Example 12-2 Sample Custom Monitor Configuration (in DIAG_MODULE.xml)
<?xml version="1.0" encoding="UTF-8"?> <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"> <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 12-6 shows how the pointcut expression from Example 12-2 is parsed. (Note the use of wildcard characters.)
Table 12-6 Description of a Sample Pointcut Expression
| Pointcut Expression | Description |
|---|---|
call( * com.foo.bar.* get* (...)) |
|
call( * com.foo.bar.* get* (...))
|
|
call( * com.foo.bar.* get* (...))
|
|
call( * com.foo.bar.* get* (...))
|
|
call( * com.foo.bar.* get* (...))
|
|
This pointcut expression matches all methods in all classes in package com.foo.bar and its sub-packages. 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 are called, 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.
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 a 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:
call: Take an action when a method is invoked.
execution: Take an action when a method is executed.
The syntax for defining a pointcut expression is as follows:
pointcutExpr := orExpr ( 'OR' orExpr ) *
orExpr := andExpr ( 'AND' andExpr ) *
andExpr := 'NOT' ? termExpr
termExpr := exec_pointcut | call_pointcut | '(' pointcutExpr ')'
exec_pointcut := 'execution' '(' modifiers?
returnSpec
classSpecWithAnnotations
methodSpec '(' parameterList ')'
')'
call_pointcut := 'call' '(' returnSpec
classSpec
methodSpec '(' parameterList ')'
')'
modifiers := modifier ( 'OR' modifier ) * modifier := 'public' | 'protected' | 'private' | 'static'
returnSpec := '*' | typeSpec
classSpecWithAnnotations := '@' IDENTIFIER ( 'OR' IDENTIFIER ) * | classSpec
classSpec := '+' ? classOrMethodPattern | '*'
typeSpec := '%' ? ( primitiveType | classSpec ) ( '[]' )*
methodSpec := classOrMethodPattern
parameterList := param ( ',' param ) *
param := typeSpec | '...'
primitiveType := 'byte' | 'char' | 'boolean' | 'short' | 'int' | 'float' | 'long' | 'double' | 'void'
classOrMethodPattern := '*' ? IDENTIFIER '*'? | '*'
The following rules apply:
The asterisk wildcard character (*) can be used in class types and method names.
An ellipsis (...) in the argument list signifies a variable number of arguments of any types beyond the argument.
A percent character (%) prefix designates the value of a non-static class instantiation, parameter, or return specification as not containing nor exposing sensitive information. The use of this operator is particularly useful with the DisplayArgumentsAction action, which captures method arguments or return values. If this prefix character is not explicitly used, an asterisk string is substituted for the value that is returned; this behavior ensures that sensitive data in your application is not inadvertently transmitted when an instrumentation event captures input arguments to, or return values from, a joinpoint.
Note:
The% operator cannot be applied to an ellipsis or to a wildcarded type within a pointcut expression.A plus sign (+) prefix to a class type identifies all subclasses, sub-interfaces or concrete classes implementing the specified class/interface pattern.
A pointcut expression specifies a pattern to identify matching joinpoints. An attempt to match a joinpoint against it will return a boolean, indicating a valid match (or not).
Pointcut expressions can be combined with AND, OR and NOT boolean operators to build complex pointcut expression trees.
For example, the following pointcut matches method executions of all public initialize methods in all classes in package com.foo.bar and its sub-packages. The initialize 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 (call sites) 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>
You can use JDK-style annotations in class and method specifiers of execution points. A class or method specifier starting with @ is interpreted as an annotation name.
When used as a class specifier, the annotation matches all classes that are annotated with it. While performing the match, only annotation names are considered. Annotation attributes are ignored.
For example, consider the following pointcut:
execution(public void @Service @Invocation (...)
The preceding pointcut matches methods that:
Are public method
Return void
Are contained in a class that is annotated with @Service
Have a method annotated with @Invocation
Contain any number of arguments.
Note:
Annotation-based specifiers can be used only with execution pointcuts. They cannot be used with call pointcuts.Annotation-based class and method specifiers can use the following wildcard characters:
The asterisk wildcard (*) matches everything.
The asterisk wildcard (*) at the beginning matches class/interface or method names that end with the given string. For example, *Bean matches with weblogic.management.configuration.ServerMBean.
The asterisk wildcard (*) at the end matches class/interface or method names that end with the given string. For example, weblogic.* matches all classes and interfaces that are in weblogic and its sub-packages.
You can specify a pointcut based on names of inner classes. For example:
public class Foo {
class Bar {
public int getValue() {...}
}
}
You can define a pointcut that covers the getValue method of the inner class Bar using the following specification:
execution (public int Foo$Bar getValue(...));
You can also use wildcard characters as follows. The following pointcut matches only the getter methods in the inner class Bar of class Foo:
execution ( * Foo$Bar get*(...));
You can also use leading and trailing wildcard characters. The following examples also match the getter methods in class Foo$Bar:
execution ( * Foo$Ba* get*(...)); execution ( * *oo$Bar get*(...)); execution ( * *oo$Ba* get*(...));
If you have configured server-scoped or application-scoped instrumentation, you can display request performance data in the WebLogic Server Administration Console. The Request Performance page displays information about the real-time and historical views of method performance that has been captured by means of the WebLogic Diagnostics Framework instrumentation capabilities.
To create request performance data, the following criteria must be met:
A WLDF system resource must be created and targeted to the server. Create the system resource as described in Instrumentation Configuration Files. You can do this using the WebLogic Server Administration Console or the WebLogic Scripting Tool (WLST).
Instrumentation in the targeted WLDF system resource must be enabled.
Application instrumentation must be enabled with a weblogic-diagnostics.xml descriptor, which you create in the application's META-INF directory, as described in Instrumentation Configuration Files.
Application instrumentation descriptors must use TraceElapsedTimeAction diagnostic actions attached to Around diagnostic monitor types. For example, a descriptor could contain the following:
<instrumentation>
<enabled>true</enabled>
<wldf-instrumentation-monitor>
<name>Connector_Around_Inbound</name>
<action>TraceElapsedTimeAction</action>
</wldf-instrumentation-monitor>
</instrumentation>
Note:
WebLogic Server does not require theweblogic-diagnostics.xml descriptor to be pre-bundled in your application's archive in order to make instrumentation changes to a deployed application.
If your application uses a deployment plan, and you enable Java HotSwap before deploying your application, you can make instrumentation changes at run time without redeploying your application.
If your deployed application does not have a deployment plan and you modify the application's instrumentation configuration, the Administration Console automatically creates a deployment plan for you and prompts you for the location in which to save it.
If Java HotSwap is not enabled in your deployment plan, or if you do not use a deployment plan, changes to some instrumentation settings require redeployment.
For more information, see Chapter 15, "Deploying WLDF Application Modules."
See Appendix B, "WLDF Instrumentation Library," for a list of "Around" type monitors.
For information about creating and analyzing request performance data in the WebLogic Server Administration Console, see "Analyze request performance" in the Oracle WebLogic Server Administration Console Online Help.