Configuring and Using the WebLogic Diagnostic Framework

Configuring the Diagnostic Context

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), attach a context to the request (defined by a unique ID and by flags that represent the characteristics of the request), and then trigger instrumentation events based on the context of the request. You can then use these instrumentation events to generate logs and trigger notifications.

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 detail throughout this chapter, which contains the following topics:

• About the Contents, Life Cycle, and Configuration of a Diagnostic Context
• Overview of the Process
• Configuring the Dye Vector via the DyeInjection Monitor
• Configuring Delegating Monitors to Use Dye Filtering
• How Dye Masks Filter Requests To Pass to Monitors
• Using Throttling to Control the Volume of Instrumentation Events

 

---

About the 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.

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

About 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, etc.

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.0. The dye flag ADDR2 is configured to indicate that a request originated from IP address 127.0.0.1. If a request from IP address 127.0.0.0 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 watch to examine every request that is dyed with ADDR1, that is, that originated from IP address 127.0.0.0.

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 About the 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.

The administrator configures a diagnostic module to use the DyeInjection monitor.
The administrator enables instrumentation for the module.
The administrator configures the DyeInjection monitor by assigning values to dyes, for example, USER1=username1, USER2=username2, ADDR1=ip_address1, ADDR2=ip_address2, and so forth.
When a request enters the system, WLDF creates and instantiates a context for the request. The context includes a unique ID and a dye vector, as described in the following step.
When a request enters the system, the DyeInjection monitor examines the request to see which dye values in the dye vector match attributes of the request, if any. For example, it checks to see if the request originated with username1 or username2, and it checks to see if the request came from ip_address1 or ip_address2.
For each dye value that matches a request attribute, the DyeInjection monitor "injects" that dye into the request. This is done by setting the dye flag for that dye in the dye vector attached to the request. For example, if a request originates with username2 from ip_address1, the DyeInjection monitor sets the dye flags USER2 and ADDR1. (USER1 and ADDR2, therefore, remain unset.)
The dye vector travels with the request (as part of the diagnostic context) as it flows through the system. This 64-bit dye vector contains only flags, not values. So, in this example, the dye vector contains only two flags that are explicitly set (USER2 and ADDR1).

Note: All dye vectors also contain one of the implicit PROTOCOL dyes, as explained in Configuring the Dye Vector via the DyeInjection Monitor.

The administrator enables dye filtering in one or more delegating diagnostic monitors and configures the dye mask for each monitor. If the dyes set in the dye mask exactly match the dyes in the dye vector attached to a request--that is, if ((dye-mask & dye-vector) == dye-mask)--the diagnostic action for the monitor will be triggered when that request is processed.

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:

Create and enable a diagnostic module for the server or servers you want to monitor.
Enable Instrumentation for the module.
Configure and enable the DyeInjection monitor for the module. (Only one DyeInjection monitor can be used with a module at any one time.)

To configure the DyeInjection monitor, you assign values to the dyes in the dye vector. The available dye flags are described in Table 10-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.0, assign the value admin@avitek to USER1 and assign the value 127.0.0.0 to ADDR1. Then, when user admin@avitek initiates a request from a client with IP address 127.0.0.0, 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.

Figure 10-1 Setting Dye Values in the Administration Console

 

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

Listing 10-1 Sample DyeInjection Monitor Configuration

<wldf-resource>
  <name>MyAdminModule</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.

Table 10-1 Request Protocols for Supported Diagnostic Context Dyes

Dye Flags	Description
ADDR1 ADDR2 ADDR3 ADDR4	The ADDR1, ADDR2, ADDR3 and ADDR4 dyes can be used to specify the IP addresses of clients that originate requests. These dye flags are set in the diagnostic context for a request if the request was originated from an IP address specified by the respective property (ADDR1, ADDR2, ADDR3, ADDR4) of the DyeInjection monitor.
CONNECTOR1 CONNECTOR2 CONNECTOR3 CONNECTOR4	The CONNECTOR1, CONNECTOR2, CONNECTOR3 and CONNECTOR4 dyes can be used to identify characteristics of connector drivers. These dye flags are set by the connector drivers to identify request properties specific to their situations. You do not configure these directly in the Administration console or in the descriptor files. The connector drivers can assign values to these dyes (using the Connector API), so information about the connections can be carried in the diagnostic context.
COOKIE1 COOKIE2 COOKIE3 COOKIE4	COOKIE1, COOKIE2, COOKIE3 and COOKIE4 are set in the diagnostic context for an HTTP/S request, if the request contains the cookie named weblogic.diagnostics.dye and its value is equal to the value of the respective property (COOKIE1, COOKIE2, COOKIE3, COOKIE4) of the DyeInjection monitor.
DYE_0 DYE_1 DYE_2 DYE_3 DYE_4 DYE_5 DYE_6 DYE_7	DYE_0 to DYE_7 are available only for use by application developers. See Using weblogic.diagnostics.context.
PROTOCOL_HTTP PROTOCOL_IIOP PROTOCOL_JRMP PROTOCOL_RMI PROTOCOL_SOAP PROTOCOL_SSL PROTOCOL_T3	The DyeInjection monitor implicitly identifies the protocol used for a request and sets the appropriate dye(s) in the dye vector, according to the protocol(s) used. PROTOCOL_HTTP is set in the diagnostic context of a request if the request uses HTTP or HTTPS protocol. PROTOCOL_IIOP is set in the diagnostic context of a request if it uses IIOP protocol. PROTOCOL_JRMP is set in the diagnostic context of a request if it uses JRMP protocol. PROTOCOL_RMI is set in the diagnostic context of a request if it uses RMI protocol. PROTOCOL_SSL is set in the diagnostic context of a request if it uses SSL protocol. PROTOCOL_T3 is set in the diagnostic context of a request if the request uses T3 or T3s protocol
THROTTLE	The THROTTLE dye is set in the diagnostic context of a request if it satisfies requirements specified by THROTTLE_INTERVAL and/or THROTTLE_RATE properties of the DyeInjection monitor.
USER1 USER2 USER3 USER4	The USER1, USER2, USER3 and USER4 dyes can be used to specify the user names of clients that originate requests. These dye flags are set in the diagnostic context for a request if the request was originated by a user specified by the respective property (USER1, USER2, USER3, USER4) of the DyeInjection monitor.

 

About the PROTOCOL Dye Flags

You must explicate 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.

About the 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 (however, see the following note).

Note: In the Administration Console, you can create diagnostic contexts only by enabling the DyeInjection monitor. However, through WLST, you can set the DiagnosticContextEnabled attribute on the WLDFServerDiagnosticMBean.

 

---

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 Connector_After_Inbound diagnostic monitor that has a TraceAction action attached to it. If dye filtering is not enabled, any request that is handled by Connector_After_Inbound (that is, any request that exits a method) 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.0, as explained below:

Configure the DyeInjection monitor so that ADDR1=127.0.0.0, and enable the DyeInjection monitor. For instructions, see Configuring the Dye Vector via the DyeInjection Monitor, earlier in this section.
Configure a dye mask and enable dye filtering for the Connector_After_Inbound diagnostic monitor. In the Administration Console, you do this in the Settings for Connector_After_Inbound page, as described below and shown in Figure 10-2.
Navigate to the Settings for Connector_After_Inbound page. (See the Administration Console online help for complete instructions for adding and configuring the Connector_After_Inbound diagnostic monitor in a diagnostic module.)
In the Dye Mask field of the Settings for Connector_After_Inbound page, move ADDR1 from the Available list to the Chosen list.
Select the EnableDyeFiltering check box.

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

Figure 10-2 Setting Dye Filtering in the Administration Console

 

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

Listing 10-2 Sample Configuration for Using Dye Filtering in a Delegating Monitor

<wldf-resource>
  <name>MyAdminModule</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>Connector_After_Inbound</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:

• The DyeInjection monitor is enabled for the diagnostic module. (If the DyeInjection monitor is not added or is disabled, dye filtering is disabled.)
• Dye filtering for the delegating or custom monitor is enabled.
• The request's dye vector contains all the dyes that are defined in the dye mask. (The dye vector can also contain dyes that are not in the dye mask, but the dye mask cannot contain dyes that are not in the dye vector.)

 

---

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.

• THROTTLE_INTERVAL sets an interval (in milliseconds) after which a new incoming request is dyed with the THROTTLE dye.

If the THROTTLE_INTERVAL is greater than 0, the DyeInjection monitor sets the THROTTLE dye flag in the dye vector of an incoming request if the last request dyed with THROTTLE arrived at least THROTTLE_INTERVAL before the new request. For example, if THROTTLE_INTERVAL=3000, the DyeInjection monitor waits at least 3000 milliseconds before it will dye an incoming request with THROTTLE.

• THROTTLE_RATE sets the rate (in terms of the number of incoming requests) by which new incoming requests are dyed with the THROTTLE dye.

If THROTTLE_RATE is greater than 0, the DyeInjection monitor sets the THROTTLE dye flag in the dye vector of an incoming request when the number of requests since the last request dyed with THROTTLE equals THROTTLE_RATE. For example, if THROTTLE_RATE = 6, every sixth request is dyed with THROTTLE.

THROTTLE_INTERVAL and THROTTLE_RATE can be used together. Both conditions must be satisfied for a request to be dyed with THROTTLE. For example, if THROTTLE_RATE=6, but the sixth request (after the last THROTTLE-dyed request) arrives before THROTTLE_INTERVAL has elapsed, the sixth request will not be dyed. The next request after THROTTLE_INTERVAL elapses will be dyed, and the counting for the THROTTLE_RATE will be reset. Conversely, if THROTTLE_INTERVAL elapses, but the number of requests since the last THROTTLE-dyed request is not greater than or equal to the THROTTLE_RATE, no incoming request will be dyed until the THROTTLE_RATE is reached.

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.

Figure 10-3 Configuring the THROTTLE Dye

 

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

Listing 10-3 Sample THROTTLE Configuration in the DyeInjection Monitor

    <wldf-instrumentation-monitor>
      <name>DyeInjection</name>
      <properties>
        THROTTLE_INTERVAL=3000
          THROTTLE_RATE=6
        </properties>
      </wldf-instrumentation-monitor>

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

Listing 10-4 Sample Configuration for Setting THROTTLE in a Dye Mask of a Delegating Monitor

    <wldf-instrumentation-monitor>
      <name>Connector_After_Inbound</name>
      <enabled>true</enabled>
      <dye-mask>THROTTLE</dye-mask>
    </wldf-instrumentation-monitor>

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, earlier in this section. One of those dyes can be the THROTTLE dye, so that you can filter on THROTTLE, just like any other dye. However, the most common way to use THROTTLE is to use it without dye filtering to restrict which requests are passed to delegating monitors.

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

• If dye filtering for a delegating or custom monitor is enabled and that monitor has a dye mask, filtering is performed based on the dye mask. That mask may include the THROTTLE dye, but it does not have to. If THROTTLE is included in a dye mask, then THROTTLE must also be included in the request's dye vector for the request to be passed to the monitor. However, if THROTTLE is not included in the dye mask, all qualifying requests are passed to the monitor, whether their dye vectors include THROTTLE or not.
• If dye filtering for a delegating or custom monitor is not enabled and neither THROTTLE property is set in the DyeInjection monitor, dye filtering will not take place and throttling will not take place.
• If dye filtering for a delegating or custom monitor is not enabled and THROTTLE is configured in the DyeInjection monitor, delegating monitors ignore dye masks but do check for the presence of the THROTTLE dye in all requests. Only those requests dyed with THROTTLE are passed to the delegating monitors for handling. Therefore, by setting a THROTTLE_RATE and/or THROTTLE_INTERVAL in the DyeInjection monitor, you reduce the number of requests handled by all delegating monitors. You do not have to configure dye masks for all your delegating monitors to take advantage of throttling.
• If dye filtering for a delegating or custom monitor is enabled and the only dye set in a dye mask is THROTTLE, only those requests that are dyed with THROTTLE are passed to the delegating monitor. This behavior is the same as when dye filtering is not enabled and THROTTLE is configured in the DyeInjection monitor.

 

---

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:

• Inspect a diagnostics context's immutable context ID.
• Inspect the settings of the dye flags in a context's dye vector.
• Retrieve an array of valid dye flag names.
• Set, or unset, the DYE_0 through DYE_7 flags in a context's dye vector. (Note that there is no way to set these flag bits via XML. You can configure DyeInjection monitor <properties> to set the non-application-specific flag bits via XML, but setDye() is the only method for setting DYE_0 through DYE_7 in a dye vector.)
• Create a dye mask for its own use.
• Attach a payload (a String) to a diagnostic context, or read an existing payload.

An application cannot:

• Set any flags in a dye vector other the eight flags reserved for applications.
• Prevent another application for setting the same application flags in a dye vector. A well-behaved application can test whether a dye flag is set before setting it.
• Prevent another application from replacing a payload. A well-behaved application can test for the presence of a payload before adding one.

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

Listing 10-5 Example: DiagnosticContextExample.java

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));
 }
}