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 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-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.
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. Some actions (for example, TraceElapsedTimeAction
) generate an event payload.
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:
TraceAction
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:
DisplayArgumentsAction
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:
TraceElapsedTimeAction
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:
StackDumpAction
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:
ThreadDumpAction
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.
To configure the Harvester to collect data gathered by the MethodInvocationStatisticsAction instances, you have to configure an instance of WLDFHarvesterBean with:
Name=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)
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.
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)(*)(*)(*)
com.Foo.Bar
class.MethodInvocationStatistics(com.foo.Bar)(doIt)()(*)
doIt()
method that has no input arguments. MethodInvocationStatistics(com.foo.Bar)(doIt)(*)(*)
doIt()
methods. MethodInvocationStatistics(com.foo.Bar)(doIt)(int, *)(*)
doIt(int)
and doIt(int, String)
methods. MethodInvocationStatistics(com.foo.Bar)(doIt)(String[])(*)
doIt(String[])
method. Array parameters use the []
pair following the type name. Spaces are insignificant for the Harvester.MethodInvocationStatistics(com.foo.Bar)(doIt)(String, ?)(*)
doIt(String, int)
and doIt(String, String)
methods. MethodInvocationStatistics(com.foo.Bar)(doNothing)(com.foo.Baz)(min|max)
doNothing()
method with the single input parameter of type com.foo.Baz
. Note: | Using a wildcard in the className can impact performance. |
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.
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.