Rename '*GuideDB' directories to their actual HTML site target names

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

1 files changed, 158 insertions, 0 deletions

diff --git a/docs/pdguide/trace.adoc b/docs/pdguide/trace.adoc
new file mode 100644
index 000000000..a752e0262
--- /dev/null
+++ b/docs/pdguide/trace.adoc
@@ -0,0 +1,158 @@
+[[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
+....