Configuring Instrumentation 11-7
11.3.2 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-INFweblogic-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 enabledtrueenabled
wldf-instrumentation-monitor nameServlet_Before_Servicename
enabledtrueenabled dye-maskUSER1dye-mask
dye-filtering-enabledtruedye-filtering-enabled actionTraceActionaction
wldf-instrumentation-monitor wldf-instrumentation-monitor
nameMyCustomMonitorname enabledtrueenabled
actionTraceActionaction location-typebeforelocation-type
pointcutcall 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 12, Configuring the DyeInjection Monitor to Manage Diagnostic Contexts,
for information about configuring the DyeInjection monitor.
Table 11–3 describes the wldf-instrumentation-monitor elements.
Table 11–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.
11-8 Configuring and Using the Diagnostics Framework for Oracle WebLogic Server
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 12, 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 Section 11.5.4.1,
Defining Pointcuts for Custom Monitors.
Table 11–3 Cont. wldf-instrumentation-monitor XML Elements in the DIAG_
MODULE.xml or weblogic-diagnostics.xml file Element
Description
Configuring Instrumentation 11-9
Additional information on dye-filtering-enabled and dye-mask follows:
■
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 requests 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 requests diagnostic context does not match the
monitors 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 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 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 diagnostic monitors in application-scoped instrumentation. See the include
description, above.
Table 11–3 Cont. wldf-instrumentation-monitor XML Elements in the DIAG_
MODULE.xml or weblogic-diagnostics.xml file Element
Description
11-10 Configuring and Using the Diagnostics Framework for Oracle WebLogic Server
Thus, the dye filtering mechanism allows monitors to take diagnostic actions only for specific requests, without slowing down other requests. See
Chapter 12, Configuring the DyeInjection Monitor to Manage Diagnostic Contexts,
for detailed information on diagnostic contexts and dye vectors.
11.3.3 Mapping wldf-instrumentation-monitor XML Elements to Monitor Types
Kategori