Configure Instrumentation And Control Devices Pdf

[Jordan Tucker]

TheInstrumentation component of the WebLogic Diagnostics Framework (WLDF) provides a mechanism for adding diagnostic code to WebLogic Server instances and the applications running on them. The key features provided by WLDF Instrumentation are:

Diagnostic monitors. A diagnostic monitor is a dynamically manageable unit of diagnostic code which is inserted into server or application code at specific locations. You define monitors by scope (system or application) and type (standard, delegating, or custom).

Diagnostic context. A diagnostic context is contextual information, such as unique request identifier and flags which the indicate presence of certain request properties such as originating IP address or user identity. The diagnostic context provides a means for tracking program execution and for controlling when monitors trigger their diagnostic actions. See Chapter 12, "Configuring the DyeInjection Monitor to Manage Diagnostic Contexts."

WLDF provides a library of predefined diagnostic monitors and actions. You can also create application-scoped custom monitors, where you control the locations where diagnostic code is inserted in the application.

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 monitor's scope.

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_NAME/config/diagnostics 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_PATH/META-INF directory for the deployed application.

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 . Pointcuts are described in 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 .

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 monitor's 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.

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 level. For more information, see Chapter 12, "Configuring the DyeInjection Monitor to Manage Diagnostic Contexts."

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.

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.

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 and elements are mandatory for a custom monitor.

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 XML Elements for information on setting a dye mask for a monitor.

Diagnostic actions execute diagnostic code that is appropriate for the associated delegating or custom monitor (standard monitors have predefined actions). In order for a delegating or custom monitor to perform any useful work, you must configure at least one action for the monitor.

Actions must be correctly matched with monitors. For example, the TraceElapsedTime action is compatible with a delegating or custom monitor whose diagnostic location type is around. See Appendix B, "WLDF Instrumentation Library," for more information.

Instrumentation is configured as part of a diagnostics descriptor, an XML configuration file, whose name and location depend on whether you are implementing system-level (server-scoped) or application-level (application-scoped) instrumentation:

This directory can contain multiple system-level diagnostic descriptor files. Filenames are arbitrary but must be terminated with.xml (myDiag.xml is a valid filename). Each file can contain configuration information for one or more of the deployable diagnostic components: Harvester, Instrumentation, or Watch and Notification. An section in a descriptor file can configure one or more diagnostic monitors. Server-scoped instrumentation can be enabled, disabled, and reconfigured without restarting the server.

Only one WLDF system resource (and hence one system-level diagnostics descriptor file) can be active at a time for a server (or cluster). The active descriptor is linked and targeted from the following configuration file:

For more information about configuring diagnostic system modules, see Configuring Diagnostic System Modules. For general information about the creation, content, and parsing of configuration files in WebLogic Server, see Understanding Domain Configuration for Oracle WebLogic Server.

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:

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).

An optional element specifying the list of classes where instrumented code can be inserted. Wildcards (*) are supported. You can specify multiple elements. If specified, a class must satisfy an pattern for it to be instrumented.

As classes are loaded, they must pass an include/exclude pattern check before any instrumentation code is inserted. Even if a class passes the include/exclude 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 include/exclude 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 and/or elements. You can probably ignore these elements for small applications or for medium-to-large applications that are loaded infrequently.

An optional element specifying the list of classes where instrumented code cannot be inserted. Wildcards (*) are supported. You can specify multiple elements. If specified, classes satisfying an pattern are not instrumented.

Diagnostic monitors are defined in elements, which are children of the element in a DIAG_MODULE.xml descriptor for server-scoped instrumentation or the META-INF/weblogic-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.)

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.

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.

3a8082e126