Overview of the Steps Required to Instrument an Application Creating a Descriptor File for a Delegating Monitor

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