Configuring and Using the WebLogic Diagnostics Framework

Configuring the DyeInjection Monitor to Manage Diagnostic Contexts

The WLDF Instrumentation component provides the means for uniquely identifying requests and tracking them as they flow through the system. You can configure WLDF to check for certain characteristics of every request that enters the system (such as the originating user or client address) and then attach a context to the request. The context is defined by a unique ID and by flags that represent the characteristics of the request. Context IDs are recorded in the log and can be used to:

Diagnostic context is available at both the system level and the application level, with some differences in how it is configured and used.

The process of configuring and using diagnostic context is described in the following sections:

Contents, Life Cycle, and Configuration of a Diagnostic Context

A diagnostic context contains a unique context ID and a dye vector, which identifies characteristics of the context.

Context Life Cycle and the Context ID

The diagnostic context for a request is created and initialized when the request enters the system; for example, when a client makes an HTTP request. The context remains attached to the request, even as the request crosses thread boundaries and Java Virtual Machine (JVM) boundaries. The diagnostic context lives for the duration of the life cycle of the request.

Every diagnostic context is identified by an ID that is unique in the domain. Because the ID travels with the request, it is possible to track given requests as they flow through the system.

Dyes, Dye Flags, and Dye Vectors

Contextual information travels with a request as a 64-bit dye vector, where each bit is a flag to identify the presence of a dye. Each dye represents one attribute of a request; for example, an originating user, an originating client IP address, access protocol, and so on.

When a dye flag for a given attribute is set, it indicates that the attribute is present. When the flag is not set, it indicates the attribute is not present.

For example, consider a configuration where the dye ADDR1 is configured to indicate that a request originated from IP address 127.0.0.1. The dye flag ADDR2 is configured to indicate that a request originated from IP address 127.0.0.2. If a request from IP address 127.0.0.1 enters the system, the ADDR1 dye flag in the dye vector for the request is set. The ADDR2 dye flag remains unset.

Diagnostic and monitoring features that take advantage of the diagnostic context can examine the dye vector to determine if an attribute is present. In the example above, the administrator could configure a diagnostic monitor to trace every request that is dyed with ADDR1, that is, that originated from IP address 127.0.0.1.

The dye vector also contains a THROTTLE dye, which is used to set how often incoming requests are dyed. For more information about this special dye, see THROTTLE Dye Flag.

For a list of the available dyes and the attributes they represent, see Dyes Supported by the DyeInjection Monitor. The process of configuring dye vectors and using them is discussed throughout the rest of this chapter.

Where Diagnostic Context Is Configured

Diagnostic context is configured as part of a diagnostic module. The primary mechanism for configuring the diagnostic context is the DyeInjection monitor, which is a standard diagnostic monitor. The joinpoints where the DyeInjection monitor is woven into the code are those locations where a request can enter the system. The diagnostic action is to check every request against the DyeInjection monitor’s configuration, then create and attach a context to the request, setting dye flags as appropriate. For information about diagnostic monitor types, pointcuts (which define the joinpoints), and diagnostic actions, see Configuring Instrumentation.

Overview of the Process

This overview describes the configuration and use of context in a server-scoped diagnostic module.

These steps are discussed in more detail in the following sections.

Configuring the Dye Vector via the DyeInjection Monitor

To create contexts for requests, you must:

To configure the DyeInjection monitor, you assign values to the dyes in the dye vector. The available dye flags are described in Table 11-1. When WLDF evaluates an incoming request to create a context for it, it checks for the presence of the values specified in the dye vector. When a value is present, WLDF sets that flag. This process is called dyeing the request or injecting a dye into the request.

For example, to monitor all requests initiated by a user named admin@avitek from a client at IP address 127.0.0.1, assign the value admin@avitek to USER1 and assign the value 127.0.0.1 to ADDR1. Then, when user admin@avitek initiates a request from a client with IP address 127.0.0.1, that request is dyed with USER1 and ADDR1; in other words the USER1 and ADDR1 flags in the dye vector (in the context for the request) are both set.

In the Administration Console, you assign values to dyes by typing them into the Properties field of the Settings for DyeInjection page.

These settings appear in the descriptor file for the diagnostic module, as shown in the following code listing.

<wldf-resource>
  <name>MyDiagnosticModule</name>
  <instrumentation>
    <enabled>true</enabled>
    <wldf-instrumentation-monitor>
      <name>DyeInjection</name>
      <enabled>true</enabled>
      <dye-mask xsi:nil="true"></dye-mask>
      <properties>ADDR1=127.0.0.1 
        USER1=admin@avitek</properties>
    </wldf-instrumentation-monitor>
  <!-- Other elements to configure instrumentation -->
  <instrumentation>
<!-- Other elements to configure this diagnostic monitor -->
<wldf-resource>

Dyes Supported by the DyeInjection Monitor

The dyes available in the dye vector are listed and explained in the following table.

PROTOCOL Dye Flags

You must explicitly set the values for the dye flags USERn, ADDRn, COOKIEn, and CONNECTORn. in the DyeInjection monitor. However, the flags PROTOCOL_HTTP, PROTOCOL_IIOP, ROTOCOL_JRMP, PROTOCOL_RMI, PROTOCOL_SOAP, PROTOCOL_SSL, and PROTOCOL_T3 are set implicitly by WLDF. When the DyeInjection monitor is enabled, every request is injected with the appropriate protocol dye. For example, every request that arrives via HTTP is injected with the PROTOCOL_HTTP dye.

THROTTLE Dye Flag

The THROTTLE dye flag can be used to control the volume of incoming requests that are dyed. THROTTLE is configured differently from the other flags, and WLDF uses it differently. For more information, see Using Throttling to Control the Volume of Instrumentation Events.

When Contexts Are Created

When the DyeInjection monitor is enabled in a diagnostic module, a diagnostic context is created for every incoming request. Even if no properties are explicitly set in the DyeInjection monitor, the context for every request will contain a unique context ID and a dye vector with one of the implicit PROTOCOL dyes. If the DyeInjection monitor is not added to a diagnostic module or if it is disabled, no diagnostic contexts will be created for any incoming requests.

Configuring Delegating Monitors to Use Dye Filtering

You can use the DyeInjection monitor as a mechanism to restrict when a delegating or custom diagnostic monitor in the diagnostic module is triggered. This process is called dye filtering.

Each monitor can have a dye mask, which specifies a selection of the dyes from the DyeInjection monitor. When dye filtering is enabled for a diagnostic monitor, the monitor’s diagnostic action is triggered only for those requests that meet the criteria set by the mask.

For example, consider a JDBC_Before_Start_Internal diagnostic monitor that has a TraceAction action attached to it. If dye filtering is not enabled, any request that is handled by JDBC_Before_Start_Internal will trigger a TraceAction. However, you could use a dye mask to trigger those TracActions only for requests that originated from a IP address 127.0.0.1, as explained below:

With this configuration, the TraceAction action will be triggered for the JDBC_Before_Start_Internal diagnostic monitor only for those requests that originate from IP address 127.0.0.1.

These settings are persisted to the descriptor file for the diagnostic module as shown in the following code listing.

<wldf-resource>
  <name>MyDiagnosticModule</name>
  <instrumentation>
    <enabled>true</enabled>
    <wldf-instrumentation-monitor>
      <name>DyeInjection</name>
      <enabled>true</enabled>
      <properties>ADDR1=127.0.0.1</properties>
    </wldf-instrumentation-monitor>
    <wldf-instrumentation-monitor>
      <name>JDBC_Before_Start_Internal</name>
      <dye-mask>ADDR1</dye-mask>
      <dye-filtering-enabled>true</dye-filtering-enabled>
      <action>TraceAction</action>
    </wldf-instrumentation-monitor>
  <!-- Other elements to configure instrumentation -->
  <instrumentation>
<!-- Other elements to configure this diagnostic monitor -->
<wldf-resource>

How Dye Masks Filter Requests to Pass to Monitors

A dye vector attached to a request can contain multiple dyes, and a dye mask attached to a delegating monitor can contain multiple dyes. For a delegating monitor’s dye mask to allow a monitor to take action on a request, all of the following must be true:

Dye Filtering Example

Figure 11-3 illustrates how dye filtering works, using a diagnostic module with three diagnostic monitors:

Using Throttling to Control the Volume of Instrumentation Events

Throttling is used to control the number of requests that are processed by the monitors in a diagnostic module. Throttling is configured using the THROTTLE dye, which is defined in the DyeInjection monitor.

Configuring the THROTTLE Dye

Unlike other dyes in the dye vector, the THROTTLE dye is configured through two properties.

You can use THROTTLE_INTERVAL and THROTTLE_RATE together. If either condition is satisfied, the request is dyed with the THROTTLE dye.

If you assign a value to either THROTTLE_INTERVAL or THROTTLE_RATE (or both, or neither), you are configuring the THROTTLE dye. A THROTTLE configuration setting in the Administration Console is shown in the following figure.

Listing 11-3 shows the resulting configuration in the descriptor file for the diagnostics module.

<wldf-resource>
  <name>MyDiagnosticModule</name>
  <instrumentation>
    <wldf-instrumentation-monitor>
      <name>DyeInjection</name>
      <properties>
        THROTTLE_INTERVAL=3000
        THROTTLE_RATE=6
      </properties>
    </wldf-instrumentation-monitor>
  </instrumentation>
<!-- Other elements to configure this diagnostic monitor -->
</wldf-resource>

Listing 11-4 shows the configuration for a JDBC_Before_Start_Internal delegating monitor where the THROTTLE dye is set in the dye mask for the monitor.

<wldf-resource>
  <name>MyDiagnosticModule</name>
  <instrumentation>
    <wldf-instrumentation-monitor>
      <name>JDBC_Before_Start_Internal</name>
      <enabled>true</enabled>
      <dye-mask>THROTTLE</dye-mask>
    </wldf-instrumentation-monitor>
  </instrumentation>
<!-- Other elements to configure this diagnostic monitor -->
</wldf-resource>

How Throttling is Handled by Delegating and Custom Monitors

Dye masks and dye filtering provide a mechanism for restricting which requests are passed to delegating and custom monitors for handling, based on properties of the requests. The presence of a property in a request is indicated by the presence of a dye, as discussed in Configuring the Dye Vector via the DyeInjection Monitor. One of those dyes can be the THROTTLE dye, so that you can filter on THROTTLE, just like any other dye.

The items in the following list explain how throttling is handled:

Using weblogic.diagnostics.context

The weblogic.diagnostics.context package provides applications limited access to a diagnostic context.

An application can use the weblogic.diagnostics.context.DiagnosticContextHelper APIs to perform the following functions:

An application cannot:

A monitor, or another application, that is downstream from the point where an application has set one or more of the DYE_0 through DYE_7 flags can set a dye mask to check for those flags, and take an action when the flag(s) are present in a context’s dye vector. If a payload is attached to the diagnostics context, any action taken by that monitor will result in the payload being archived, and thus available through the accessor component.

Listing 11-5 is a short example which (implicitly) creates a diagnostic context, prints the context ID, checks the value of the DYE_0 flag, and then sets the DYE_0 flag.

package weblogic.diagnostics.examples;

import weblogic.diagnostics.context.DiagnosticContextHelper;

public class DiagnosticContextExample {

 public static void main(String args[]) throws Exception {
   System.out.println("\nContextId=" +
     DiagnosticContextHelper.getContextId());
     System.out.println("isDyedWith(DYE_0)=" +
       DiagnosticContextHelper.isDyedWith(DiagnosticContextHelper.DYE_0));

     DiagnosticContextHelper.setDye(DiagnosticContextHelper.DYE_0, true);
     System.out.println("isDyedWith(DYE_0)=" +
       DiagnosticContextHelper.isDyedWith(DiagnosticContextHelper.DYE_0));
 }
}