Bug 159854 "Problem Diagnosis Guide" (first draft)

1 files changed, 86 insertions, 4 deletions

diff --git a/docs/pdGuideDB/trace.xml b/docs/pdGuideDB/trace.xml
index 85d51e97a..382d87842 100644
--- a/docs/pdGuideDB/trace.xml
+++ b/docs/pdGuideDB/trace.xml
@@ -7,9 +7,9 @@
         <para> The usual approach to opening a report on Bugzilla is to describe the symptoms of the 
         problem and attach a simple testcase. This allows the AspectJ team to try and reproduce the problem in
         an attempt to fix it as well as improve the test suite. Unfortunately it may not be possible
-        to produce such a testcase either because your program is too large or is comercially sensitive. Alternatively 
+        to produce such a testcase either because your program is too large or is commercially sensitive. Alternatively 
         the problem may relate to your specific environment where AspectJ is being used and will not be
-        reproducible by the AspectJ team. In one of these situations you may be asked to produce a
+        reproducible by the AspectJ team. In each of these situations you may be asked to produce a
         trace of the compiler when the problem occurs instead. This can then be attached to the bug report. </para>
 
         <sect2 id="configuration" xreflabel="configuration">
@@ -21,7 +21,7 @@
             that is configured using a logging.properties file. By default only error
             and fatal events will be logged but less severe warnings as well as fine grained
             method entry and exit events can be obtained using the appropriate configuration. All
-            compiler messages can also be logged through the infrastructure by setting the
+            regular compiler messages can also be logged through the infrastructure by setting the
             <literal>org.aspectj.weaving.messages</literal> System property. </para>
             
             <para> If you are using a JDK 1.4 or earlier AspectJ will use a simple built-in trace
@@ -89,7 +89,89 @@
         <sect2 id="examples" xreflabel="examples">
             <title>Examples</title>
         
-            <para>  </para>
+            <para> Using <literal>-Dorg.aspectj.tracing.factory=default</literal>
+            	to force AspectJ to use its internal infrastructure,
+            	<literal>-Dorg.aspectj.tracing.enabled=true</literal> to turn it on and  
+            	<literal>-Dorg.aspectj.tracing.messages=true</literal> to include messages
+            	running a simple HelloWorld with LTW will generate tracing to stderr. Below
+            	is an extract from that trace with method arguments removed. 
+            	You will notice the millisecond time stamp,
+            	thread id and indication of entry/exit/event or message type for each line
+            	of trace.
+            </para>
+	        <programlisting><![CDATA[
+15:44:18.630 main > org.aspectj.weaver.loadtime.Aj.<init> 
+15:44:18.660 main < org.aspectj.weaver.loadtime.Aj.<init>
+15:44:18.660 main > org.aspectj.weaver.loadtime.Aj.preProcess
+15:44:18.660 main - org.aspectj.weaver.loadtime.Aj.preProcess
+15:44:18.730 main > org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.<init>
+15:44:18.730 main < org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.<init>
+15:44:18.730 main > org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.initialize 
+15:44:18.821 main I [AppClassLoader@92e78c] info AspectJ Weaver Version DEVELOPMENT ...
+15:44:18.821 main > org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.parseDefinitions
+15:44:18.821 main I [AppClassLoader@92e78c] info register classloader ...
+15:44:18.821 main - org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.parseDefinitions 
+15:44:18.841 main - org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.parseDefinitions 
+15:44:18.841 main I [AppClassLoader@92e78c] info using configuration ...
+15:44:18.891 main < org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.parseDefinitions 
+15:44:19.021 main > org.aspectj.weaver.World$TypeMap.<init>
+15:44:19.021 main < org.aspectj.weaver.World$TypeMap.<init>
+15:44:19.021 main > org.aspectj.weaver.CrosscuttingMembersSet.<init>
+15:44:19.021 main < org.aspectj.weaver.CrosscuttingMembersSet.<init>
+15:44:19.021 main > org.aspectj.weaver.Lint.<init>
+15:44:19.021 main < org.aspectj.weaver.Lint.<init>
+15:44:19.021 main > org.aspectj.weaver.World.<init> 
+15:44:19.111 main < org.aspectj.weaver.World.<init>
+15:44:19.201 main > org.aspectj.weaver.bcel.BcelWeaver.<init> 
+15:44:19.201 main < org.aspectj.weaver.bcel.BcelWeaver.<init>
+15:44:19.201 main > org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.registerDefinitions 
+15:44:19.211 main > org.aspectj.weaver.bcel.BcelWeaver.setReweavableMode 
+15:44:19.351 main < org.aspectj.weaver.bcel.BcelWeaver.setReweavableMode
+15:44:19.351 main > org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.registerAspects 
+15:44:19.351 main I [AppClassLoader@92e78c] info register aspect Aspect
+15:44:19.351 main > org.aspectj.weaver.bcel.BcelWeaver.addLibraryAspect 
+15:44:19.501 main - org.aspectj.weaver.bcel.BcelWorld.lookupJavaClass 
+15:44:19.632 main > org.aspectj.weaver.CrosscuttingMembersSet.addOrReplaceAspect 
+15:44:19.792 main < org.aspectj.weaver.CrosscuttingMembersSet.addOrReplaceAspect 
+15:44:19.792 main < org.aspectj.weaver.bcel.BcelWeaver.addLibraryAspect 
+15:44:19.792 main < org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.registerAspects 
+15:44:19.792 main < org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.registerDefinitions 
+15:44:19.792 main > org.aspectj.weaver.bcel.BcelWeaver.prepareForWeave 
+15:44:19.822 main < org.aspectj.weaver.bcel.BcelWeaver.prepareForWeave
+15:44:19.822 main > org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.weaveAndDefineConcete...
+15:44:19.822 main < org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.weaveAndDefineConcete...
+15:44:19.822 main < org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.initialize 
+15:44:19.822 main > org.aspectj.weaver.tools.WeavingAdaptor.weaveClass 
+...            
+			]]></programlisting>
+        
+            <para> Alternatively when running under Java 5 the <literal>logging.properties</literal>
+            	file below could be used to configure Java Logging. The resulting
+            	file, just containing trace for the 
+            	<literal>org.aspectj.weaver.loadtime</literal> package, will be
+            	written to <literal>java0.log</literal> in your <literal>user.home</literal> directory. 
+            </para>
+
+	        <programlisting><![CDATA[
+handlers= java.util.logging.FileHandler
+
+.level= INFO
+
+java.util.logging.FileHandler.pattern = %h/java%u.log
+java.util.logging.FileHandler.count = 1
+java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
+java.util.logging.FileHandler.level = FINER
+
+org.aspectj.weaver.loadtime.level = FINER
+			]]></programlisting>
+        
+            <para> 
+            	By setting the System property <literal>-Dorg.aspectj.tracing.debug=true</literal>
+            	you should see a message confirming which trace infrastructure is being used.
+            </para>
+	        <programlisting><![CDATA[
+	TraceFactory.instance=org.aspectj.weaver.tools.Jdk14TraceFactory@12dacd1	        
+			]]></programlisting>
         </sect2>
     </sect1>
 </chapter>