Configuring and Using the WebLogic Diagnostic 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. The later can be used 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 of the 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
`DyeInjection`	Before	Built-in	At points where requests enter the server.
`Connector_Before_Inbound`	Before	Stateless	At entry of methods handling inbound connections.
`Connector_Before_Outbound`	Before	Stateless	At entry of methods handling outbound connections.
`Connector_Before_Work`	Before	Stateless	At entry of methods related to scheduling, starting and executing work items.
`Connector_Before_Tx`	Before	Stateless	Entry of transaction register, unregister, start, rollback and commit methods.
`Connector_After_Inbound`	Server	Stateless	At exit of methods handling inbound connections.
`Connector_After_Outbound`	After	Stateless	At exit of methods handling outbound connections.
`Connector_After_Work`	After	Stateless	At exit of methods related to scheduling, starting and executing work items.
`Connector_After_Tx`	After	Stateless	At exit of transaction register, unregister, start, rollback and commit methods.
`Connector_Around_Inbound`	Around	Around	At entry and exit of methods handling inbound connections.
`Connector_Around_Outbound`	Around	Around	At entry and exit of methods handling outbound connections.
`Connector_Around_Work`	Around	Around	At entry and exit of methods related to scheduling, starting and executing work items.
`Connector_Around_Tx`	Around	Around	At entry and exit of transaction register, unregister, start, rollback and commit methods.
JDBC_Before_Connection_Internal	Before	Stateless	Before calls to methods: `Driver.connect DataSource.getConnection`
JDBC_Before_Start_Internal	Before	Stateless
JDBC_Before_Commit_Internal	Before	Stateless
JDBC_Before_Rollback_Internal	Before	Stateless
JDBC_Before_Statement_Internal	Before	Stateless
JDBC_After_Connection_Internal	Before	Stateless
JDBC_After_Start_Internal	After	Stateless
JDBC_After_Commit_Internal	After	Stateless
JDBC_After_Rollback_Internal	After	Stateless
JDBC_After_Statement_Internal	After	Stateless

The following table 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
`Servlet_Before_Service`	Before	Stateless	At method entries 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_Before_Tags`	Before	Stateless	Before calls to jsp methods: `Tag.doStartTag Tag.doEndTag`
`JNDI_Before_Lookup`	Before	Stateless	Before calls to `javax.naming.Context` lookup methods `Context.lookup*`
`JMS_Before_ TopicPublished`	Before	Stateless	Before call to methods: `TopicPublisher.publish`
`JMS_Before_MessageSent`	Before	Stateless	Before call to methods: `QueSender send`
`JMS_Before_ AsyncMessageReceived`	Before	Stateless	At entry of methods: `MessageListener.onMessage`
`JMS_Before_ SyncMessageReceived`	Before	Stateless	Before calls to methods: `MessageConsumer.receive*`
`JDBC_Before_ GetConnection`	Before	Stateless	Before calls to methods: `Driver.connect DataSource.getConnection`
`JDBC_Before_ CloseConnection`	Before	Stateless	Before calls to methods: `Connection.close`
`JDBC_Before_ CommitRollback`	Before	Stateless	Before calls to methods: `Connection.commit Connection.rollback`
`JDBC_Before_Statement`	Before	Stateless	Before calls to methods: `Connection.prepareStatement Connection.prepareCall Statement.addBatch RowSet.setCommand`
`JDBC_Before_Execute`	Before	Stateless	Before calls to methods: `Statement.execute* PreparedStatement.execute*`
`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`
`EJB_Before_ SessionEjbBusinessMethods`	Before	Stateless	At entry of all `SessionBean` 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_Entity EjbSemanticMethods`	Before	Stateless	At entry of methods: `EnitityBean.set* EnitityBean.get* EnitityBean.ejbFind* EnitityBean.ejbHome* EnitityBean.ejbSelect* EnitityBean.ejbCreate* EnitityBean.ejbPostCreate*`
`EJB_Before_EntityEjb BusinessMethods`	Before	Stateless	At entry of all `EntityBean` methods, which are not standard ejb methods.
`MDB_Before_Message Received`	Before	Stateless	At entry of methods: `MessageDrivenBean.onMessage`
`MDB_Before_Set MessageDrivenContext`	Before	Stateless	At entry of methods: `MessageDrivenBean.setMessage DrivenContext`
`MDB_Before_Remove`	Before	Stateless	At entry of methods: `MessageDrivenBean.ejbRemove`
`JTA_Before_Start`	Before	Stateless	At entry of methods: `UserTransaction.begin`
`JTA_Before_Commit`	Before	Stateless	At entry of methods: `UserTransaction.commit`
`JTA_Before_Rollback`	Before	Stateless	At entry of methods: `UserTransaction.rollback`
`Servlet_After_Service`	After	Stateless	At method exits of servlet/jsp methods: `HttpJspPage._jspService Servlet.service HttpServlet.doGet HttpServlet.doPost Filter.doFilter`
`Servlet_After_Session`	After	Stateless	After calls to servlet methods: `HttpServletRequest.getSession HttpSession.setAttribute/putValue HttpSession.getAttribute/getValue HttpSession.removeAttribute/ removeValue HttpSession.invalidate`
`Servlet_After_Tags`	After	Stateless	After calls to jsp methods: `Tag.doStartTag Tag.doEndTag`
`JNDI_After_Lookup`	After	Stateless	After calls to `javax.naming.Context` lookup methods: `Context.lookup*`
`JMS_After_Topic Published`	After	Stateless	After call to methods: `TopicPublisher.publish`
`JMS_After_MessageSent`	After	Stateless	After call to methods: `QueSender send`
`JMS_After_ AsyncMessageReceived`	After	Stateless	At exits of methods: `MessageListener.onMessage`
`JMS_After_Sync MessageReceived`	After	Stateless	After calls to methods: `MessageConsumer.receive*`
`JDBC_After_Get Connection`	After	Stateless	After calls to methods: `Driver.connect DataSource.getConnection`
`JDBC_After_ CloseConnection`	After	Stateless	After calls to methods: `Connection.close`
`JDBC_After_Commit Rollback`	After	Stateless	After calls to methods: `Connection.commit Connection.rollback`
`JDBC_After_Statement`	After	Stateless	After calls to methods: `Connection.prepareStatement Connection.prepareCall Statement.addBatch RowSet.setCommand`
`JDBC_After_Execute`	After	Stateless	After calls to methods: `Statement.execute* PreparedStatement.execute*`
`EJB_After_ SessionEjbMethods`	After	Stateless	At exits of methods: `SessionBean.setSessionContext SessionBean.ejbRemove SessionBean.ejbActivate SessionBean.ejbPassivate`
`EJB_After_SessionEjb SemanticMethods`	After	Stateless	At exits of methods: `SessionBean.ejbCreate SessionBean.ejbPostCreate`
`EJB_After_SessionEjb BusinessMethods`	After	Stateless	At exits of all `SessionBean` methods, which are not standard ejb methods.
`EJB_After_EntityEjb Methods`	After	Stateless	At exits of methods: `EnitityBean.setEntityContext EnitityBean.unsetEntityContext EnitityBean.ejbRemove EnitityBean.ejbActivate EnitityBean.ejbPassivate EnitityBean.ejbLoad EnitityBean.ejbStore`
`EJB_After_EntityEjb SemanticMethods`	After	Stateless	At exits of methods: `EnitityBean.set* EnitityBean.get* EnitityBean.ejbFind* EnitityBean.ejbHome* EnitityBean.ejbSelect* EnitityBean.ejbCreate* EnitityBean.ejbPostCreate*`
`EJB_After_EntityEjb BusinessMethods`	After	Stateless	At exits of all `EntityBean` methods, which are not standard ejb methods.
`MDB_After_Message Received`	After	Stateless	At exits of methods: `MessageDrivenBean.onMessage`
`MDB_After_SetMessageDrivenContext`	After	Stateless	At exits of methods: `MessageDrivenBean.setMessage DrivenContext`
`MDB_After_Remove`	After	Stateless	At exits of methods: `MessageDrivenBean.ejbRemove`
`JTA_After_Start`	After	Stateless advice	At exits of methods: `UserTransaction.begin`
`JTA_After_Commit`	After	Stateless advice	At exits of methods: `UserTransaction.commit`
`JTA_After_Rollback`	After	Stateless advice	At exits of methods: `UserTransaction.rollback`
`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_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_Around_Tags`	Around	Around	Before and after calls to jsp methods: `Tag.doStartTag Tag.doEndTag`
`JNDI_Around_Lookup`	Around	Around	Before and after calls to `javax.naming.Context` lookup methods `Context.lookup*`
`JMS_Around_Topic Published`	Around	Around	Before and after call to methods: `TopicPublisher.publish`
`JMS_Around_Message Sent`	Around	Around	Before and after call to methods: `QueSender send`
`JMS_Around_Async MessageReceived`	Around	Around	At entry and exits of methods: `MessageListener.onMessage`
`JMS_Around_Sync MessageReceived`	Around	Around	Before and after calls to methods: `MessageConsumer.receive*`
`JDBC_Around_Get Connection`	Around	Around	Before and after calls to methods: `Driver.connect DataSource.getConnection`
`JDBC_Around_Close Connection`	Around	Around	Before and after calls to methods: `Connection.close`
`JDBC_Around_CommitRollback`	Around	Around	Before and after calls to methods: `Connection.commit Connection.rollback`
`JDBC_Around_ Statement`	Around	Around	Before and after calls to methods: `Connection.prepareStatement Connection.prepareCall Statement.addBatch RowSet.setCommand`
`JDBC_Around_Execute`	Around	Around	Before and after calls to methods: `Statement.execute* PreparedStatement.execute*`
`EJB_Around_Session EjbMethods`	Around	Around	At entry and exits of methods: `SessionBean.setSessionContext SessionBean.ejbRemove SessionBean.ejbActivate SessionBean.ejbPassivate`
`EJB_Around_SessionEjbSemanticMethods`	Around	Around	At entry and exits of methods: `SessionBean.ejbCreate SessionBean.ejbPostCreate`
`EJB_Around_SessionEjbBusinessMethods`	Around	Around	At entry and exits of all `SessionBean` methods, which are not standard ejb methods.
`EJB_Around_EntityEjbMethods`	Around	Around	At exits of methods: `EnitityBean.setEntityContext EnitityBean.unsetEntityContext EnitityBean.ejbRemove EnitityBean.ejbActivate EnitityBean.ejbPassivate EnitityBean.ejbLoad EnitityBean.ejbStore`
`EJB_Around_EntityEjb SemanticMethods`	Around	Around	At entry and exits of methods: `EnitityBean.set* EnitityBean.get* EnitityBean.ejbFind* EnitityBean.ejbHome* EnitityBean.ejbSelect* EnitityBean.ejbCreate* EnitityBean.ejbPostCreate*`
`EJB_Around_EntityEjb BusinessMethods`	Around	Around	At entry and exits of all `EntityBean` methods that are not standard ejb methods.
`MDB_Around_MessageReceived`	Around	Around	At entry and exits of methods: `MessageDrivenBean.onMessage`
`MDB_Around_Set MessageDrivenContext`	Around	Around	At entry and exits of methods: `MessageDrivenBean.setMessage DrivenContext`
`MDB_Around_Remove`	Around	Around	At entry and exits of methods: `MessageDrivenBean.ejbRemove`
`JTA_Around_Start`	Around	Around	At entry and exits of methods: `UserTransaction.begin`
`JTA_Around_Commit`	Around	Around	At entry and exits of methods: `UserTransaction.commit`
`JTA_Around_Rollback`	Around	Around	At entry and exits of methods: `UserTransaction.rollback`

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 with which they are compatible, as indicated by the Compatible Monitor Type column.

TraceAction

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

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

Timestamp
Context identifier from the diagnostic context which uniquely identifies the request
Transaction identifier, if available
User identity
Action type, that is, TraceAction
Domain
Server name
Instrumentation scope name (for example, application name)
Diagnostic monitor name
Location in code from where the action was called (class name, method name, etc.)
Payload carried by the diagnostic context, if any

DisplayArgumentsAction

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

A DisplayArgumentsAction generates an instrumentation event at affected location in the program execution to capture method arguments or return value. The following information is generated:

When executed, this action causes an instrumentation event which will be dispatched to the events archive. When attached to before monitors, the instrumentation event will capture input arguments to the joinpoint (for example, method arguments). When attached to after monitors, the instrumentation event will capture the return value from the joinpoint. The even will carry the following information:

Timestamp
Context identifier from the diagnostic context which uniquely identifies the request
Transaction identifier, if available
User identity
Action type, that is, DisplayArgumentsAction
Domain
Server name
Instrumentation scope name (for example, application name)
Diagnostic monitor name
Location in code from where the action was called (class name, method name, etc.)
Payload carried by the diagnostic context, if any
Input arguments, if any, when attached to before monitors
Return value, if any, when attached to after monitors

TraceElapsedTimeAction

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

An TraceElapsedTimeAction generates an instrumentation event at affected location in the program execution to capture elapsed times.

When executed, this action captures the timestamps before and after the execution of 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 will carry the following information:

Timestamp
Context identifier from the diagnostic context which uniquely identifies the request
Transaction identifier, if available
User identity
Action type, that is, TraceElapsedTimeAction
Domain
Server name
Instrumentation scope name (for example, application name)
Diagnostic monitor name
Location in code from where the action was called (class name, method name, etc.)
Payload carried by the diagnostic context, if any
Elapsed time processing the joinpoint, as event payload

StackDumpAction

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

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

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

Timestamp
Context identifier from the diagnostic context which uniquely identifies the request
Transaction identifier, if available
User identity
Action type, that is, StackDumpAction
Domain
Server name
Instrumentation scope name (for example, application name)
Diagnostic monitor name
Location in code from where the action was called (class name, method name, etc.)
Payload carried by the diagnostic context, if any
Stack trace as event payload

ThreadDumpAction

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

A ThreadDumpAction generates an instrumentation event at affected location in the program execution to capture thread dump, if the underlying VM supports it.

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

Timestamp
Context identifier from the diagnostic context which uniquely identifies the request
Transaction identifier, if available
User identity
Action type, that is, ThreadDumpAction
Domain
Server name
Instrumentation scope name (for example, application name)
Diagnostic monitor name
Location in code from where the action was called (class name, method name, etc.)
Payload carried by the diagnostic context, if any
Thread dump as event payload