Context Life Cycle and the Context ID Dyes, Dye Flags, and Dye Vectors

12-2 Configuring and Using the Diagnostics Framework for Oracle WebLogic Server

12.1.1 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 diagnostic 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 a Context ID that is unique in the domain. Because the Context ID travels with the request, it is possible to determine the events and log entries associated with a given request as it flows through the system.

12.1.2 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 flag ADDR1 is configured to indicate a request that originated from IP address 127.0.0.1. ■ the flag ADDR2 is configured to indicate a request that originated from IP address 127.0.0.2. ■ the flag USER1 is configured to indicate a request that originated from user adminavitek.com. If a request from IP address 127.0.0.1 enters the system from a user other than adminavitek.com, the ADDR1 flag in the dye vector for the request is set. The ADDR2 and USER1 dye flags remain unset. If a request from adminavitek.com enters the system from an IP address other than 127.0.0.1 or 127.0.0.2, the USER1 flag in the dye vector for the request is set. The ADDR1 and ADDR2 dye flags remain unset. If a request from adminavitek.com from IP address 127.0.0.2 enters the system, both the USER1 and ADDR2 flags in the dye vector for this request are set. The ADDR1 flag remains unset. Diagnostic and monitoring features that take advantage of the diagnostic context can examine the dye vector to determine if one or more attributes are present that is, the associated flag is set. In the example above, you 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. You could also configure a diagnostic monitor that traces every request that is dyed with both ADDR1 and USER1, that is, the request originated from user adminavitek.com at IP address 127.0.0.1 requests from other users at 127.0.0.1 would not be traced. 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 Section 12.3.3, THROTTLE Dye Flag. For a list of the available dyes and the attributes they represent, see Section 12.3.1, Dyes Supported by the DyeInjection Monitor. The process of configuring dye vectors and using them is discussed throughout the rest of this chapter. Configuring the DyeInjection Monitor to Manage Diagnostic Contexts 12-3

12.1.3 Where Diagnostic Context Is Configured