Configuring Instrumentation 11-13
11.5.2 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
Section 11.4, Configuring Server-Scoped Instrumentation.
2. Create a well formed META-INFweblogic-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: enabledtrueenabled.
■
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 Section 11.5.3, Creating a Descriptor File for a Delegating Monitor,
and Section 11.5.4, Creating a Descriptor File for a Custom Monitor,
for samples of well-formed descriptor files.
See Section 11.5.4.1, Defining Pointcuts for Custom Monitors,
for information on creating a pointcut expression.
3. Put the descriptor file in the application archive.
4. Deploy the application. See
Chapter 14, Deploying WLDF Application Modules. Keep the following points in mind:
■
The diagnostic monitors defined in weblogic-diagnostics.xml will be listed on the Deployments: server_name: Configuration: Instrumentation
page of the Administration Console.
■
If the META-INFweblogic-diagnostics.xml descriptor in the application archive defines a monitor, it cant be removed using the Administration Console. It can,
however, 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 applications deployment plan. Any monitors that were added in this way can be deleted using the
Administration Console.
11.5.3 Creating a Descriptor File for a Delegating Monitor
The following example shows a well-formed META-INFweblogic-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. You can, however, define multiple monitors in the
descriptor file.
wldf-resource xmlns=http:xmlns.oracle.comweblogicweblogic-diagnostics xmlns:xsi=http:www.w3.org2001XMLSchema-instance
Note: In WLS 10.3, you are not required to create a
weblogic-diagnostics.xml file in the applications META-INF directory, as was the case in previous WLS releases. You can,
however, still use this method to initially configure diagnostic monitors for your application.
11-14 Configuring and Using the Diagnostics Framework for Oracle WebLogic Server
xsi:schemaLocation=http:xmlns.oracle.comweblogicweblogic-diagnostics1.0webl ogic-diagnostics.xsd
instrumentation enabledtrueenabled
wldf-instrumentation-monitor nameServlet_Before_Servicename
enabledtrueenabled dye-maskUSER1dye-mask
dye-filtering-enabledtruedye-filtering-enabled actionTraceActionaction
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.
11.5.4 Creating a Descriptor File for a Custom Monitor