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.

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

JDBC_After_Reserve_Connection_Internal

After

Stateless

After a JDBC connection is reserved from the connection pool.

JDBC_After_Release_Connection_Internal

After

Stateless

After a JDBC connection is released back to the connection pool.

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.

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

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

Module name

Location in code from where the action was called, which consists of:

Class name

Method name

Method signature

Line number

Thread name

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 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:

Timestamp

Context identifier from the diagnostic context that 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

Module name

Location in code from where the action was called, which consists of:

Class name

Method name

Method signature

Line number

Thread name

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.

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:

Timestamp

Context identifier from the diagnostic context that 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

Module name

Location in code from where the action was called, which consists of:

Class name

Method name

Method signature

Line number

Thread name

Payload carried by the diagnostic context, if any

Elapsed time processing the joinpoint, as event payload, in nanoseconds

TraceMemoryAllocationAction

This action uses the JRockit API to trace the number of bytes allocated by a thread during a method call. This action is very similar to TraceElapsedTimeAction, with the exception that the memory allocated within a method call is traced.

The TraceMemoryAllocationAction action:

Creates an instrumentation event that is persisted.

Can be used from delegating and custom monitors.

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:

Timestamp

Context identifier from the diagnostic context that 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

Module name

Location in code from where the action was called, which consists of:

Class name

Method name

Method signature

Line number

Thread name

Payload carried by the diagnostic context, if any

Stack trace as an 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 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:

Timestamp

Context identifier from the diagnostic context that 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

Module name

Location in code from where the action was called, which consists of:

Class name

Method name

Method signature

Line number

Thread name

Payload carried by the diagnostic context, if any

Thread dump as an event payload

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:

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.

className is 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 is 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.

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.

Harvest the min and max execution time for the doNothing() method with the single input parameter of type com.foo.Baz.

Note:

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.

MethodMemoryAllocationStatisticsAction

The MethodMemoryAllocationStatisticsAction uses the JRockit API that tracks the number of bytes allocated by a thread during a method call. Statistics are kept in-memory on the memory allocations, and instrumentation events are not created by this action.

The MethodMemoryAllocationStatisticsAction is very similar to the existing MethodInvocationStatisticsAction, except that the statistics tracked by MethodMemoryAllocationStatisticsAction are related to the memory allocated within a method call.

The MethodInvocationStatisticsAction does not create an instrumentation event. When JRockit is available, the statistics are available through the WLDFInstrumentationRuntimeMBean.

The following statistics for each method are kept:

count

min

max

avg

sum

sum_of_squares

std_deviation

Scripting on this page enhances content navigation, but does not change the content in any way.