123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186 |
- <chapter id="trace" xreflabel="Tracing">
- <title>Tracing</title>
-
- <sect1 id="trace-introduction">
- <title>Introduction</title>
-
- <para>
- The AspectJ developers have instrumented the compiler/weaver with
- many "trace" messages for their own debugging use. These remain in
- the production releases because tracing helps when it is hard to
- isolate the problem in a test case. This sections describes how
- to enable tracing so you can provide trace information on bug reports.
- </para>
- <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 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 each of these situations you can produce a
- trace of the compiler when the problem occurs instead. This can then be attached to the bug report. </para>
-
- <sect2 id="trace-configuration" xreflabel="Configuring Tracing">
- <title>Configuring Tracing</title>
-
- <para> When available (Java 5 or later) AspectJ will use the
- <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/logging/index.html">
- java.util.logging</ulink> infrastructure
- configured using a <literal>logging.properties</literal> 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
- 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 running the AspectJ compiler/weaver under JDK 1.4 or earlier,
- AspectJ will use a simple built-in trace
- infrastructure that logs to stderr. This is enabled by setting the
- <literal>org.aspectj.weaving.tracing.enabled</literal> System property. You may also override
- the default behaviour or provide your own trace implementation using the
- <literal>org.aspectj.weaving.tracing.factory</literal> System property. </para>
-
- <para> The table below lists the System properties that can be used to configure tracing. </para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>org.aspectj.tracing.debug</literal>
- </entry>
- <entry>
- Enable simple debugging of the trace infrastructure itself.
- <para> Default: <literal>false</literal>. </para>
- </entry>
- </row>
- <row>
- <entry>
- <literal>org.aspectj.tracing.enabled</literal>
- </entry>
- <entry>
- Enable the built-in AspectJ trace infrastructure.
- <para> Default: <literal>false</literal>. </para>
- </entry>
- </row>
- <row>
- <entry>
- <literal>org.aspectj.tracing.factory</literal>
- </entry>
- <entry>
- Select trace infrastructure. Specify the fully qualified class name
- of the <literal>org.aspectj.weaver.tools.TraceFactory</literal>
- interface to use a custom infrastructure. Specify a value of
- <literal>default</literal> to force AspectJ to use it's
- built-in infrastructure.
- </entry>
- </row>
- <row>
- <entry>
- <literal>org.aspectj.tracing.messages</literal>
- </entry>
- <entry>
- Enable tracing of compiler messages. The kind of messages logged
- is determined by the selected trace infrastructure not the message
- configuration.
- <para> Default: <literal>false</literal>. </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
-
- <sect2 id="trace-examples" xreflabel="trace-examples">
- <title>Examples</title>
-
- <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>
|