[[trace]]
= Tracing

[[trace-introduction]]
== Introduction

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.

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.

[[trace-configuration]]
=== Configuring Tracing

When available (Java 5 or later) AspectJ will use the
http://java.sun.com/j2se/1.5.0/docs/guide/logging/index.html[java.util.logging]
infrastructure 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 regular compiler messages can also be
logged through the infrastructure by setting the
`org.aspectj.weaving.messages` System property.

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
`org.aspectj.weaving.tracing.enabled` System property. You may also
override the default behaviour or provide your own trace implementation
using the `org.aspectj.weaving.tracing.factory` System property.

The table below lists the System properties that can be used to
configure tracing.

[cols=",",options="header",]
|===
|Property |Description
|`org.aspectj.tracing.debug` a|
Enable simple debugging of the trace infrastructure itself.

Default: `false`.

|`org.aspectj.tracing.enabled` a|
Enable the built-in AspectJ trace infrastructure.

Default: `false`.

|`org.aspectj.tracing.factory` |Select trace infrastructure. Specify the
fully qualified class name of the
`org.aspectj.weaver.tools.TraceFactory` interface to use a custom
infrastructure. Specify a value of `default` to force AspectJ to use
it's built-in infrastructure.

|`org.aspectj.tracing.messages` a|
Enable tracing of compiler messages. The kind of messages logged is
determined by the selected trace infrastructure not the message
configuration.

Default: `false`.

|===

[[trace-examples]]
=== Examples

Using `-Dorg.aspectj.tracing.factory=default` to force AspectJ to use
its internal infrastructure, `-Dorg.aspectj.tracing.enabled=true` to
turn it on and `-Dorg.aspectj.tracing.messages=true` 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.

[source, text]
....
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
...
....

Alternatively when running under Java 5 the `logging.properties` file
below could be used to configure Java Logging. The resulting file, just
containing trace for the `org.aspectj.weaver.loadtime` package, will be
written to `java0.log` in your `user.home` directory.

[source, text]
....
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
....

By setting the System property `-Dorg.aspectj.tracing.debug=true` you
should see a message confirming which trace infrastructure is being
used.

[source, text]
....
TraceFactory.instance=org.aspectj.weaver.tools.Jdk14TraceFactory@12dacd1
....