Configuring Instrumentation 11-5
You can enable and disable diagnostic monitors without redeploying an application. However, you may have to redeploy the application after modifying
other instrumentation features, for example defining pointcuts or adding or removing monitors. Whether you have 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 hot-swap feature when starting the server, and deploy using a
deployment plan that has placeholders for instrumentation settings For more information about these choices, see
Section 14.2, Using Deployment Plans to Dynamically Control Instrumentation Configuration.
For more information about deploying and modifying diagnostic application modules, see
Chapter 14, Deploying WLDF Application Modules. The diagnostics XML schema is located at:
http:xmlns.oracle.comweblogicweblogic-diagnostics1.0weblog ic-diagnostics.xsd
Each diagnostics descriptor file must begin with the following lines: wldf-resource xmlns=http:xmlns.oracle.comweblogicweblogic-diagnostics
xmlns:xsi=http:www.w3.org2001XMLSchema-instance For an overview of WLDF resource configuration, see
Chapter 4, Understanding WLDF Configuration.
11.3 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.
■
Section 11.3.1, Instrumentation XML Elements, describes the top-level
elements used within an instrumentation element.
■
Section 11.3.2, wldf-instrumentation-monitor XML Elements, describes the
elements used within an wldf-instrumentation-monitor element.
■
Section 11.3.3, Mapping wldf-instrumentation-monitor XML Elements to Monitor Types,
summarizes which instrumentation elements apply to which monitors.
11.3.1 Instrumentation XML Elements
Table 11–2 describes the instrumentation elements in the DIAG_MODULE.xml file.
The following configuration fragment illustrates the use of those elements:
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.
11-6 Configuring and Using the Diagnostics Framework for Oracle WebLogic Server
wldf-resource nameMyDiagnosticModulename
instrumentation enabledtrueenabled
-- The following include element would apply only to an application-scoped Instrumentation descriptor --
includefoo.bar.com.include -- lt;wldf-instrumentation-monitorgt; elements to define diagnostic
monitors for this diagnostic module -- instrumentation
-- Other elements to configure this diagnostic module -- wldf-resource
Table 11–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 11–1 .
As classes are loaded, they must pass an includeexclude pattern check before any instrumentation code is inserted. Even if a class
passes the includeexclude 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 includeexclude 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 andor 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.
Configuring Instrumentation 11-7
11.3.2 wldf-instrumentation-monitor XML Elements
