Configuring and Using the WebLogic Diagnostics Framework

      

WLDF Instrumentation Library

The WebLogic Diagnostic Framework Instrumentation Library contains diagnostic monitors and diagnostic actions, as discussed in the following sections:

For information about using items from the Instrumentation Library, see Configuring Instrumentation.

 

Diagnostic Monitor Library

Diagnostic monitors are broadly classified as server-scoped and application-scoped monitors. The former can be used to instrument WebLogic Server classes. You use the latter to instrument application classes. Except for the DyeInjection monitor, all monitors are delegating monitors, that is, they do not have a built-in diagnostic action. Instead, they delegate to actions attached to them to perform diagnostic activity.

All monitors are preconfigured with their respective pointcuts. However, the actual locations affected by them may vary depending on the classes they instrument. For example, the Servlet_Before_Service monitor adds diagnostic code at the entry of servlet or java server page (JSP) service methods at different locations in different servlet implementations.

For any delegating monitor, only compatible actions may be attached. The compatibility is determined by the nature of the monitor.

The following table lists and describes the diagnostic monitors that can be used within server scope, that is, in WebLogic Server classes. For the diagnostic actions that are compatible with each monitor, see the Compatible Action Type column in the table.

Table B-1 Diagnostic Monitors for Use Within Server Scope


Monitor Name
Monitor Type 		Compatible Action Type

Pointcuts
Connector_Before_Inbound Before Stateless At entry of methods handling inbound connections.
Connector_After_Inbound Server Stateless At exit of methods handling inbound connections.
Connector_Around_Inbound Around Around At entry and exit of methods handling inbound connections.
Connector_Before_Outbound Before Stateless At entry of methods handling outbound connections.
Connector_After_Outbound After Stateless At exit of methods handling outbound connections.
Connector_Around_Outbound Around Around At entry and exit of methods handling outbound connections.
Connector_Before_Tx Before Stateless Entry of transaction register, unregister, start, rollback and commit methods.
Connector_After_Tx After Stateless At exit of transaction register, unregister, start, rollback and commit methods.
Connector_Around_Tx Around Around At entry and exit of transaction register, unregister, start, rollback and commit methods.
Connector_Before_Work Before Stateless At entry of methods related to scheduling, starting and executing connector work items.
Connector_After_Work After Stateless At exit of methods related to scheduling, starting and executing connector work items.
Connector_Around_Work Around Around At entry and exit of methods related to scheduling, starting and executing connector work items.
DyeInjection Before Built-in At points where requests enter the server.
JDBC_Before_Commit_Internal Before Stateless JDBC subsystem internal code
JDBC_After_Commit_Internal After Stateless JDBC subsystem internal code
JDBC_Before_Connection_
Internal 		Before Stateless Before calls to methods: Driver.connect
DataSource.getConnection
JDBC_After_Connection_ Internal Before Stateless JDBC subsystem internal code
JDBC_Before_Rollback_ Internal Before Stateless JDBC subsystem internal code
JDBC_After_Rollback_Internal After Stateless JDBC subsystem internal code
JDBC_Before_Start_Internal Before Stateless JDBC subsystem internal code
JDBC_After_Start_Internal After Stateless JDBC subsystem internal code
JDBC_Before_Statement_
Internal 		Before Stateless JDBC subsystem internal code
JDBC_After_Statement_
Internal 		After Stateless JDBC subsystem internal code

Table B-2 lists the diagnostic monitors that can be used within application scopes, that is, in deployed applications. For the diagnostic actions that are compatible with each monitor, see the Compatible Action Type column in the table.

Table B-2 Diagnostic Monitors for Use Within Application Scopes


Monitor Name
Monitor Type 		Compatible Action Type

Pointcuts
EJB_After_EntityEjbBusiness Methods After Stateless At exits of all EntityBean methods, which are not standard ejb methods.
EJB_Around_EntityEjbBusinessMethods Around Around At entry and exits of all EntityBean methods that are not standard ejb methods.
EJB_After_EntityEjbMethods After Stateless At exits of methods: EnitityBean.setEntityContext
EnitityBean.unsetEntityContext
EnitityBean.ejbRemove
EnitityBean.ejbActivate
EnitityBean.ejbPassivate
EnitityBean.ejbLoad
EnitityBean.ejbStore
EJB_Around_EntityEjbMethods Around Around At exits of methods: EnitityBean.setEntityContext
EnitityBean.unsetEntityContext
EnitityBean.ejbRemove
EnitityBean.ejbActivate
EnitityBean.ejbPassivate
EnitityBean.ejbLoad
EnitityBean.ejbStore
EJB_After_EntityEjbSemantic Methods After Stateless At exits of methods: EnitityBean.set*
EnitityBean.get*
EnitityBean.ejbFind*
EnitityBean.ejbHome*
EnitityBean.ejbSelect*
EnitityBean.ejbCreate*
EnitityBean.ejbPostCreate*
EJB_Around_EntityEjbSemanticMethods Around Around At entry and exits of methods: EnitityBean.set*
EnitityBean.get*
EnitityBean.ejbFind*
EnitityBean.ejbHome*
EnitityBean.ejbSelect*
EnitityBean.ejbCreate*
EnitityBean.ejbPostCreate*
EJB_After_SessionEjbMethods After Stateless At exits of methods: SessionBean.setSessionContext
SessionBean.ejbRemove
SessionBean.ejbActivate
SessionBean.ejbPassivate
EJB_Around_SessionEjbMethods Around Around At entry and exits of methods: SessionBean.setSessionContext
SessionBean.ejbRemove
SessionBean.ejbActivate
SessionBean.ejbPassivate
EJB_After_SessionEjbBusinessMethods After Stateless At exits of all SessionBean methods, which are not standard ejb methods.
EJB_Around_SessionEjb
BusinessMethods 		Around Around At entry and exits of all SessionBean methods, which are not standard ejb methods.
EJB_After_SessionEjbSemanticMethods After Stateless At exits of methods: SessionBean.ejbCreateSessionBean.ejbPostCreate
EJB_Around_SessionEjb
SemanticMethods 		Around Around At entry and exits of methods: SessionBean.ejbCreate
SessionBean.ejbPostCreate
EJB_Before_EntityEjbBusinessMethods Before Stateless At entry of all EntityBean methods, which are not standard ejb methods.
EJB_Before_EntityEjbMethods Before Stateless At entry of methods: EnitityBean.setEntityContext
EnitityBean.unsetEntityContext
EnitityBean.ejbRemove
EnitityBean.ejbActivate
EnitityBean.ejbPassivate
EnitityBean.ejbLoad
EnitityBean.ejbStore
EJB_Before_EntityEjbSemanticMethods Before Stateless At entry of methods: EnitityBean.set*
EnitityBean.get*
EnitityBean.ejbFind*
EnitityBean.ejbHome*
EnitityBean.ejbSelect*
EnitityBean.ejbCreate*
EnitityBean.ejbPostCreate*
EJB_Before_SessionEjb
BusinessMethods 		Before Stateless At entry of all SessionBean methods, which are not standard ejb methods.
EJB_Before_SessionEjbMethods Before Stateless At entry of methods: SessionBean.setSessionContext
SessionBean.ejbRemove
SessionBean.ejbActivate
SessionBean.ejbPassivate
EJB_Before_SessionEjb
SemanticMethods 		Before Stateless At entry of methods: SessionBean.ejbCreate
SessionBean.ejbPostCreate
HttpSessionDebug Around Built-in getSession - Inspects returned HTTP session Before and after calls to methods: getAttribute setAttribute removeAttribute At inspection points, the approximate session size is computed and stored as the payload of a generated event. The size is computed by flattening the session to a byte-array. If an error is encountered while flattening the session, a negative size is reported.
JDBC_Before_CloseConnection Before Stateless Before calls to methods: Connection.close
JDBC_After_CloseConnection After Stateless After calls to methods: Connection.close
JDBC_Around_CloseConnection Around Around Before and after calls to methods: Connection.close
JDBC_Before_CommitRollback Before Stateless Before calls to methods: Connection.commit
Connection.rollback
JDBC_After_CommitRollback After Stateless After calls to methods: Connection.commit
Connection.rollback
JDBC_Around_CommitRollback Around Around Before and after calls to methods: Connection.commit
Connection.rollback
JDBC_Before_Execute Before Stateless Before calls to methods: Statement.execute*
PreparedStatement.execute*
JDBC_After_Execute After Stateless After calls to methods: Statement.execute*
PreparedStatement.execute*
JDBC_Around_Execute Around Around Before and after calls to methods: Statement.execute*
PreparedStatement.execute*
JDBC_Before_GetConnection Before Stateless Before calls to methods: Driver.connect
DataSource.getConnection
JDBC_After_GetConnection After Stateless After calls to methods: Driver.connect
DataSource.getConnection
JDBC_Around_GetConnection Around Around Before and after calls to methods: Driver.connect
DataSource.getConnection
JDBC_Before_Statement Before Stateless Before calls to methods: Connection.prepareStatement
Connection.prepareCall
Statement.addBatch
RowSet.setCommand
JDBC_After_Statement After Stateless After calls to methods: Connection.prepareStatement
Connection.prepareCall
Statement.addBatch
RowSet.setCommand
JDBC_Around_Statement Around Around Before and after calls to methods: Connection.prepareStatement
Connection.prepareCall
Statement.addBatch
RowSet.setCommand
JMS_Before_AsyncMessage
Received 		Before Stateless At entry of methods: MessageListener.onMessage
JMS_After_AsyncMessage
Received 		After Stateless At exits of methods: MessageListener.onMessage
JMS_Around_AsyncMessage
Received 		Around Around At entry and exits of methods: MessageListener.onMessage
JMS_Before_MessageSent Before Stateless Before call to methods: QueSender send
JMS_After_MessageSent After Stateless After call to methods: QueSender send
JMS_Around_MessageSent Around Around Before and after call to methods: QueSender send
JMS_Before_SyncMessage
Received 		Before Stateless Before calls to methods: MessageConsumer.receive*
JMS_After_SyncMessage
Received 		After Stateless After calls to methods: MessageConsumer.receive*
JMS_Around_SyncMessage
Received 		Around Around Before and after calls to methods: MessageConsumer.receive*
JMS_Before_TopicPublished Before Stateless Before call to methods: TopicPublisher.publish
JMS_After_TopicPublished After Stateless After call to methods: TopicPublisher.publish
JMS_Around_TopicPublished Around Around Before and after call to methods: TopicPublisher.publish
JNDI_Before_Lookup Before Stateless Before calls to javax.naming.Context lookup methods Context.lookup*
JNDI_After_Lookup After Stateless After calls to javax.naming.Context lookup methods: Context.lookup*
JNDI_Around_Lookup Around Around Before and after calls to javax.naming.Context lookup methods Context.lookup*
JTA_Before_Commit Before Stateless At entry of methods: UserTransaction.commit
JTA_After_Commit After Stateless advice At exits of methods: UserTransaction.commit
JTA_Around_Commit Around Around At entry and exits of methods: UserTransaction.commit
JTA_Before_Rollback Before Stateless At entry of methods: UserTransaction.rollback
JTA_After_Rollback After Stateless advice At exits of methods: UserTransaction.rollback
JTA_Around_Rollback Around Around At entry and exits of methods: UserTransaction.rollback
JTA_Before_Start Before Stateless At entry of methods: UserTransaction.begin
JTA_After_Start After Stateless advice At exits of methods: UserTransaction.begin
JTA_Around_Start Around Around At entry and exits of methods: UserTransaction.begin
MDB_Before_MessageReceived Before Stateless At entry of methods: MessageDrivenBean.onMessage
MDB_After_MessageReceived After Stateless At exits of methods: MessageDrivenBean.onMessage
MDB_Around_MessageReceived Around Around At entry and exits of methods: MessageDrivenBean.onMessage
MDB_Before_Remove Before Stateless At entry of methods: MessageDrivenBean.ejbRemove
MDB_After_Remove After Stateless At exits of methods: MessageDrivenBean.ejbRemove
MDB_Around_Remove Around Around At entry and exits of methods: MessageDrivenBean.ejbRemove
MDB_Before_SetMessageDriven
Context 		Before Stateless At entry of methods: MessageDrivenBean.setMessage
DrivenContext
MDB_After_SetMessageDriven
Context 		After Stateless At exits of methods: MessageDrivenBean.setMessageDrivenContext
MDB_Around_SetMessageDriven
Context 		Around Around At entry and exits of methods: MessageDrivenBean.setMessageDrivenContext
Servlet_Before_Service Before Stateless At method entries of servlet/jsp methods: HttpJspPage._jspService
Servlet.service
HttpServlet.doGet
HttpServlet.doPost
Filter.doFilter
Servlet_After_Service After Stateless At method exits of servlet/jsp methods: HttpJspPage._jspService
Servlet.service
HttpServlet.doGet
HttpServlet.doPost
Filter.doFilter
Servlet_Around_Service Around Around At method entry and exits of servlet/jsp methods: HttpJspPage._jspService
Servlet.service
HttpServlet.doGet
HttpServlet.doPost
Filter.doFilter
Servlet_Before_Session Before Stateless Before calls to servlet methods: HttpServletRequest.getSession
HttpSession.setAttribute/
putValue
HttpSession.getAttribute/
getValue
HttpSession.removeAttribute/
removeValue
HttpSession.invalidate
Servlet_Around_Session Around Around Before and after calls to servlet methods: HttpServletRequest.getSession
HttpSession.setAttribute/
putValue
HttpSession.getAttribute/
getValue
HttpSession.removeAttribute/
removeValue
HttpSession.invalidate
Servlet_After_Session After Stateless After calls to servlet methods: HttpServletRequest.getSession
HttpSession.setAttribute/
putValue
HttpSession.getAttribute/
getValue
HttpSession.removeAttribute/
removeValue
HttpSession.invalidate
Servlet_Before_Tags Before Stateless Before calls to jsp methods: Tag.doStartTag
Tag.doEndTag
Servlet_After_Tags After Stateless After calls to jsp methods: Tag.doStartTag
Tag.doEndTag
Servlet_Around_Tags Around Around Before and after calls to jsp methods: Tag.doStartTag
Tag.doEndTag

 

Diagnostic Action Library

The Diagnostic Action Library includes the following actions:

These diagnostic actions can be used with the delegating monitors described in the previous tables. They can also be used with custom monitors that you can define and use within applications. Each diagnostic action can only be used with monitors which they are compatible, as indicated by the Compatible Monitor Type column. Some actions (for example, TraceElapsedTimeAction) generate an event payload.

 

TraceAction

This action is a stateless action and is compatible with Before and After monitor types.

A TraceAction generates a trace event at the affected location in the program execution. The following information is generated:

 

DisplayArgumentsAction

This action is a stateless action and is compatible with Before and After monitor types.

A DisplayArgumentsAction generates an instrumentation event at the affected location in the program execution to capture method arguments or a return value.

When executed, this action causes an instrumentation event that is dispatched to the events archive. When attached to before monitors, the instrumentation event captures input arguments to the joinpoint (for example, method arguments). When attached to after monitors, the instrumentation event captures the return value from the joinpoint. The event carries the following information:

 

TraceElapsedTimeAction

This action is an Around action and is compatible with Around monitor types.

A TraceElapsedTimeAction generates two events: one before and one after the location in the program execution.

When executed, this action captures the timestamps before and after the execution of an associated joinpoint. It then computes the elapsed time by computing the difference. It generates an instrumentation event which is dispatched to the events archive. The elapsed time is stored as event payload. The event carries the following information:

 

StackDumpAction

This action is a stateless action and is compatible with Before and After monitor types.

A StackDumpAction generates an instrumentation event at the affected location in the program execution to capture a stack dump.

When executed, this action generates an instrumentation event which is dispatched to the events archive. It captures the stack trace as an event payload. The event carries following information:

 

ThreadDumpAction

This action is a stateless action and is compatible with Before and After monitor types.

A ThreadDumpAction generates an instrumentation event at the affected location in the program execution to capture a thread dump, if the underlying VM supports it. JDK 1.5 (Oracle JRockit and Sun) supports this action.

This action generates an instrumentation event which is dispatched to the events archive. This action may be used only with the JRockit JVM. It is ignored when used with other JVMs. It captures the thread dump as event payload. The event carries the following information:

 

MethodInvocationStatisticsAction

This action is an Around action and is compatible with Around monitor types.

A MethodInvocationStatisticsAction computes method invocation statistics in memory without persisting an event for each invocation. It makes the collected information available through the InstrumentationRuntimeMBean. The collected information is consumable by the Harvester and the Watch-Notifications components. This makes it possible to create watch rules that can combine request information from the instrumentation system and metric information from other runtime MBeans.

The WLDFInstrumentationRuntimeMBean instance for a given scope exposes the data collected from the MethodInvocationStatisticsAction instances attached to the configured Diagnostic Around monitors, using the MethodInvocationStatisics attribute. This attribute returns a map with a nested structure that has the following semantics: 

  MethodInvocationStatistics::= Map<className, MethodMap>

  MethodMap::= Map<methodName, MethodParamsSignatureMap>

  MethodParamsSignatureMap::= Map<MethodParamsSignature, MethodDataMap>

  MethodDataMap::= <MetricName, Statistic>

  MetricName:= min | max | avg | count | sum | sum_of_squares | std_deviation

The first level of entries is keyed by the fully qualified class names. The next level yields a map called MethodMap, whose keys are method names and values of another nested map structure, MethodParamsSignatureMap. MethodParamsSignatureMap contains entries that are keyed by a String representation of the method input argument signature to return another map instance, MethodDataMap. MethodDataMap has a fixed set of keys for the names of the different kinds of supported metrics.

Configuring the Harvester to Collect MethodInvocationStatisticsAction Data

To configure the Harvester to collect data gathered by the MethodInvocationStatisticsAction instances, you have to configure an instance of WLDFHarvesterBean with: 

Name of=weblogic.management.runtime.WLDFInstrumentationRuntimeMBean

The scope is selected by the instance configuration.

The attribute specification defines the data that is collected by the Harvester. The successive elements of the map are accessed by using the following notation: 

MethodInvocationStatistics(className)(methodName)(methodParamSignature)

(metricName)



  
        
     className


        
     The fully qualified Java class name. You can use the ‘*' wildcard in a class name.




        
     methodName


        
     Selects a specific method from the given class. You can use the ‘*' wildcard in a method name. 




        
     methodParamSignature


        
     A string that is a comma-separated list of a method's input argument types. Only the Java type names are included in the signature specification without the argument names. As in the Java language, the order of the parameters in the signature is significant. 


This element also supports the ‘*' wildcard, so you do not have to specify the entire list of input argument types for a method. ‘*' matches zero or more argument types at the position following its occurrence in the methodParamSignature expression. 


You can also use the ‘?' wildcard to match a single argument type at any given position in the ordered list of parameter types. 


Both of these wildcards can appear anywhere in the expression. See MethodInvocationStatistics Examples. 



        
     metricName


        
     The statistics to harvest. You can use the ‘*' wildcard in this key to harvest all of the supported metrics.

MethodInvocationStatistics Examples

Consider a class with the following overloaded methods: 

package.com.foo;

public interface Bar {

  public void doIt();

  public void doIt(int a);

  public void doit(int a, String s)

  public void doIt(Stringa, int b);

  public void doIt(String a, String b);

  public void doIt(String[] a);

  public void doNothing();

  public void doNothing(com.foo.Baz);

}

The following examples show how to use harvest various statistics: 

MethodInvocationStatistics(com.foo.Bar)(*)(*)(*)
Harvests all statistics for all methods in the com.Foo.Bar class. 
MethodInvocationStatistics(com.foo.Bar)(doIt)()(*)
Harvests all statistics for the doIt() method that has no input arguments. 
MethodInvocationStatistics(com.foo.Bar)(doIt)(*)(*)
Harvests all statistics for all doIt() methods. 
MethodInvocationStatistics(com.foo.Bar)(doIt)(int, *)(*)
Harvests all statistics for the doIt(int) and doIt(int, String) methods. 
MethodInvocationStatistics(com.foo.Bar)(doIt)(String[])(*)
Harvests all statistics for the doIt(String[]) method. Array parameters use the [] pair following the type name. Spaces are insignificant for the Harvester. 
MethodInvocationStatistics(com.foo.Bar)(doIt)(String, ?)(*)
Harvest all statistics for the doIt methods with two input parameters and String as the first argument type. Using the example class, this would match the doIt(String, int) and doIt(String, String) methods. 
MethodInvocationStatistics(com.foo.Bar)(doNothing)(com.foo.Baz)(min|max)
Harvest the min and max execution time for the doNothing() method with the single input parameter of type com.foo.Baz.

Using a wildcard in the className can impact performance.

Configuring Watch Rules Based on MethodInvocationStatistics Metrics

You can use the same syntax described in the previous sections to use MethodInvocationStatistics metrics in a watch rule. You can create meaningful watch rules that do not wildcard the MetricName element, and instead specify whether you are interested in the min, max, avg, count, sum, sum_of_squares, or std_deviation variable for a given method.

Using JMX to Collect Data

When using straight JMX to collect data, you can potentially impact server performance if you invoke the getAttribute(“MethodInvocationStatistics”) method on the WLDFInstrumentationRuntimeMBean. This is because, depending on the instrumented classes, the nested map structure can contain a lot of data that will involve expensive serialization.

It is more advisable to use the getMethodInvocationStatisticsData(String) method when using JMX to collect data.