Diagnostic Monitor Types Concepts and Terminology

11-2 Configuring and Using the Diagnostics Framework for Oracle WebLogic Server ■ Section 11.1.5, Diagnostic Actions

11.1.1 Instrumentation Scope

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. However, there are differences, and they are discussed throughout this documentation. The term server-scoped instrumentation refers to instrumentation configuration and features specific to WebLogic Server instances and clusters. Application-scoped instrumentation refers to configuration and features specific to applications deployed on WebLogic servers. The scope is built in to each diagnostic monitor; you cannot modify a monitors scope.

11.1.2 Configuration and Deployment

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_ NAMEconfigdiagnostics 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_PATHMETA-INF directory for the deployed application.

11.1.3 Joinpoints, Pointcuts, and Diagnostic Locations

Instrumentation code is inserted into 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 andor exit point 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 used to describe a pointcut is pointcut. Pointcuts are described in Section 11.5.4.1, 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 used to describe a diagnostic location is location-type.

11.1.4 Diagnostic Monitor Types

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 monitors pointcut, diagnostic location, and actions. For example, Servlet_Around_Service is an application-scoped delegating monitor, which can be used to trigger diagnostic actions at the entry to and at the exit of certain servlet and JSP methods. There are three types of instrumentation 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 Configuring Instrumentation 11-3 level. For more information, see Chapter 12, 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 the monitor will perform. In that sense, 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. In order for a delegating monitor to perform any useful work, you must assign at least one action to the monitor. 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 are using WLST or editing a descriptor file manually, you must make sure that the actions are compatible with the monitors. Validation is performed when the XML 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 a delegating monitor, which is available only for application-scoped instrumentation, and does not have a predefined pointcut or location. You assign a name to a custom monitor, define the pointcut and the diagnostics location the monitor will use, and then assign actions from the set of predefined diagnostic actions. The pointcut and location type elements are mandatory for a custom monitor. Table 11–1 summarizes the differences among the types of monitors. You can restrict when a diagnostic action is triggered by setting a dye mask on a monitor. This mask determines which dye flags in the diagnostic context trigger actions. See Section 11.3.2, wldf-instrumentation-monitor XML Elements, for information on setting a dye mask for a monitor.

11.1.5 Diagnostic Actions