com.goldencode.p2j.aspects.ltw

Class MethodTraceAspect

java.lang.Object

com.goldencode.p2j.aspects.ltw.MethodTraceAspect

public abstract class MethodTraceAspect
extends java.lang.Object

An abstract aspect to capture profile data (invocation count and aggregate time) per method. The aspect is designed for load-time weaving using a concrete aspect subclass defined in an aop.xml file. That concrete aspect must define a pointcut for the abstract scope() method.

Although the tracing advice implementation is designed to introduce as little overhead as possible, the overhead is quite noticeable while data collection is active (less so while it is disabled). This overhead will be reflected in the collected data, and it should be taken into account when analyzing the results. Part of the overhead is due to the load-time weaving of this aspect with the classes it is measuring. This weaving is done once, when the target class is first loaded into the JVM. To minimize the impact of this one-time weave on the trace results, it is recommended to perform the work flow to be measured once before starting data collection, then perform it again with data collection turned on. However, this is not always possible, if what is being measured is the first-time execution of a code path, where future executions will be short-circuited by caching of various resources by the runtime.

Due to the aforementioned overhead which this feature introduces to running code, it is recommended not to enable this feature in production deployments.

Tracing is controlled by the enableDataCollection(boolean) method. When an active tracing session is disabled, all data which has been collected up to that point is post-processed and written to a CSV file, then discarded.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	MethodTraceAspect.BucketData A class which organizes method trace data into specific buckets.
private static class	MethodTraceAspect.ByTotalTime A comparator which sorts trace data objects into descending order by total elapsed time.
private static class	MethodTraceAspect.Call Representation of a method invocation which identifies the caller and the callee methods, optimized for use as a hash map key.
private static interface	MethodTraceAspect.ElapsedTimeable An interface with one method to return elapsed time.
private static class	MethodTraceAspect.MethodIdentifier A wrapper for a method, optimized for use as a hash map key.
private static class	MethodTraceAspect.TraceBucket Trace data for a single analysis bucket, including the trace data itself and an aggregate of all the traces' own times.
private static class	MethodTraceAspect.TraceData Data structure containing invocation count and aggregate elapsed time for a method call.

Field Summary

Fields

Modifier and Type	Field and Description
private static java.lang.String[]	buckets Package "buckets" for data post-processing
private static java.lang.ThreadLocal<java.util.Deque<MethodTraceAspect.TraceData>>	callStack Thread-local stack of trace data since entering the first join point in the traced code
private static java.lang.String	CSV_FILE Fixed name of CSV output file (written to current directory)
private static java.lang.String	DATA_OUTPUT The name of the folder where the trace data will be dumped to be used by the HTML UI
private static boolean	enabled Flag which controls data collection
private static CentralLogger	LOG Logger
private static java.lang.String	METHOD_LIST_FILE Fixed name of all methods list CSV output file (written to current directory)
private static java.lang.String	SUMMARY_FILE Fixed name of summary CSV output file (written to current directory)
private static java.lang.String	TRACE_OUTPUT The name of the folder in which the HTML UI artifacts will be generated
private static java.util.Map<MethodTraceAspect.Call,MethodTraceAspect.TraceData>	traceData Map of profile data by method signature
private static long	traceStart Start time of a trace session, in milliseconds

Constructor Summary

Constructors

Constructor and Description
MethodTraceAspect()

Method Summary

Modifier and Type	Method and Description
private static java.util.Map<MethodTraceAspect.MethodIdentifier,MethodTraceAspect.TraceData>	aggregatePerMethod() Retrieve a map between each tracked method and its trace data.
static void	enableDataCollection(boolean enable) Enable or disable data collection.
private static void	exportHTML() Routine used for generating a HTML UI used for better interpreting of the data.
private static void	generateAux(java.util.List<java.lang.String> roots) Helper method for HTML UI generation.
private static java.util.Map<MethodTraceAspect.MethodIdentifier,MethodTraceAspect.BucketData>	getBucketsByRoot() Utility method used by both HTML and CSV UI.
private static java.lang.String	matchBucket(MethodTraceAspect.MethodIdentifier ident) Attempt to match a method's declaring class with a data bucket identifier.
private static void	processData() Post-process the collected trace data and write the result to a CSV file.
abstract void	scope() An abstract pointcut which should be defined for load-time weaving inside a concrete-aspect element within META-INF/aop.xml.
java.lang.Object	trace(org.aspectj.lang.ProceedingJoinPoint joinPoint) The primary tracing advice which collects trace information about calls to the target methods.
private static void	writeAllMethods(java.io.BufferedWriter bw) Utility method for dumping all the methods traces together with count and own time.
private static void	writeGrandTotals(java.io.BufferedWriter bw, int len, long[] totals, long grandTotalElapsed) Utility method for CSV exporting of the data.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOG

private static final CentralLogger LOG

Logger

TRACE_OUTPUT

private static java.lang.String TRACE_OUTPUT

The name of the folder in which the HTML UI artifacts will be generated

DATA_OUTPUT

private static java.lang.String DATA_OUTPUT

The name of the folder where the trace data will be dumped to be used by the HTML UI

CSV_FILE

private static java.lang.String CSV_FILE

Fixed name of CSV output file (written to current directory)

SUMMARY_FILE

private static java.lang.String SUMMARY_FILE

Fixed name of summary CSV output file (written to current directory)

METHOD_LIST_FILE

private static java.lang.String METHOD_LIST_FILE

Fixed name of all methods list CSV output file (written to current directory)

enabled

private static volatile boolean enabled

Flag which controls data collection

traceStart

private static long traceStart

Start time of a trace session, in milliseconds

traceData

private static final java.util.Map<MethodTraceAspect.Call,MethodTraceAspect.TraceData> traceData

Map of profile data by method signature

callStack

private static final java.lang.ThreadLocal<java.util.Deque<MethodTraceAspect.TraceData>> callStack

Thread-local stack of trace data since entering the first join point in the traced code

buckets

private static final java.lang.String[] buckets

Package "buckets" for data post-processing

Constructor Detail

MethodTraceAspect

public MethodTraceAspect()

Method Detail

enableDataCollection

public static void enableDataCollection(boolean enable)

Enable or disable data collection. Upon disabling data collection, any collected results are processed and exported.

Parameters:

enable - true to start data collection; false to stop it and process the results.

exportHTML

private static void exportHTML()

Routine used for generating a HTML UI used for better interpreting of the data. The end-user interface groups the method tracing on roots and buckets.

generateAux

private static void generateAux(java.util.List<java.lang.String> roots)
                         throws java.io.IOException

Helper method for HTML UI generation. This ensures that the requires JS and CSS are generated for the index HTML. Otherwise, functionality may lack.

Parameters:

roots - A list of all JS files we created containing information about multiple traced methods. These should be dumped in the loader JS which ensures that the data is loaded in the JS memory.

Throws:

java.io.IOException

getBucketsByRoot

private static java.util.Map<MethodTraceAspect.MethodIdentifier,MethodTraceAspect.BucketData> getBucketsByRoot()

Utility method used by both HTML and CSV UI. This groups all tracked bucket data per "root" (the method which determined the execution of all methods from the bucket).

Returns:

A map of bucket data grouped by the root / scenario.

processData

private static void processData()

Post-process the collected trace data and write the result to a CSV file. This involves organizing the data into "buckets", each representing a transition from one code framework to another. Only the trace data for the first method call in each new bucket is retained, as it represents the aggregate time spent in that method and all of its called methods. This reduced data set is then sorted in descending order by aggregate time spent in the outermost method call across each set of buckets. This sorted data is then written out to a CSV file.

writeAllMethods

private static void writeAllMethods(java.io.BufferedWriter bw)
                             throws java.io.IOException

Utility method for dumping all the methods traces together with count and own time.

Parameters:

bw - The writter where this statistic should be written.

Throws:

java.io.IOException

aggregatePerMethod

private static java.util.Map<MethodTraceAspect.MethodIdentifier,MethodTraceAspect.TraceData> aggregatePerMethod()

Retrieve a map between each tracked method and its trace data. This is an aggregate of all buckets. A method can appear in multiple buckets - here we compute the total time. Don't use the caller of the trace data as there is none - a trace data holds information about multiple traces. Its own time and count is in fact a total of all traces with the same method identifier.

Returns:

A map between all methods and their total own time and count across all buckets.

writeGrandTotals

private static void writeGrandTotals(java.io.BufferedWriter bw,
                                     int len,
                                     long[] totals,
                                     long grandTotalElapsed)
                              throws java.io.IOException

Utility method for CSV exporting of the data. More exactly, this prints the grand totals pe bucket fort he active method tracing.

Parameters:

bw - The writer where the grand totals shoudl be written

len - The number of buckets

totals - The total values

grandTotalElapsed - The grand total elapsed

Throws:

java.io.IOException

matchBucket

private static java.lang.String matchBucket(MethodTraceAspect.MethodIdentifier ident)

Attempt to match a method's declaring class with a data bucket identifier.

Parameters:

ident - Method identifier.

Returns:

The matching bucket identifer string, if a match was found, else null.

scope

public abstract void scope()

An abstract pointcut which should be defined for load-time weaving inside a concrete-aspect element within META-INF/aop.xml.

trace

public java.lang.Object trace(org.aspectj.lang.ProceedingJoinPoint joinPoint)
                       throws java.lang.Throwable

The primary tracing advice which collects trace information about calls to the target methods. Here we attempt the following with minimal overhead:

• Determine the caller method.
• Determine the callee method.
• Measure the elapsed number of nanoseconds it takes for the callee method to execute and add that value to a running aggregate for this method and subtract it from the own time of our calling method, if any.
• Increment the number of times this caller invoked this callee.

Data is collected safely across all threads on which calls to the traced methods are made.

The caller method is determined using a thread-local stack, which is cleared any time this advice is entered after data collection has been halted. Note that the relationship between caller and callee may represent an actual, direct invocation if both methods are crosscut by the defined pointcut. Otherwise, if intermediate method invocations are not crosscut, the recorded "caller" may actually represent some "ancestor" method further up the actual call stack. It is assumed that this potential "gap" between caller and callee is understood by and acceptable to the definer of the pointcut.

Parameters:

joinPoint - Join point which represents the method being traced.

Returns:

Object, if any, returned by the method being traced.

Throws:

java.lang.Throwable - if an exception is thrown by the method being traced.