From d4a6906b3012fac6e4dbaca5854fc59ba0d67e47 Mon Sep 17 00:00:00 2001 From: Alexander Kriegisch Date: Sat, 8 Jan 2022 11:50:55 +0700 Subject: Rename '*GuideDB' directories to their actual HTML site target names Signed-off-by: Alexander Kriegisch --- docs/pdguide/trace.adoc | 158 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 docs/pdguide/trace.adoc (limited to 'docs/pdguide/trace.adoc') 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. +15:44:18.660 main < org.aspectj.weaver.loadtime.Aj. +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. +15:44:18.730 main < org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor. +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. +15:44:19.021 main < org.aspectj.weaver.World$TypeMap. +15:44:19.021 main > org.aspectj.weaver.CrosscuttingMembersSet. +15:44:19.021 main < org.aspectj.weaver.CrosscuttingMembersSet. +15:44:19.021 main > org.aspectj.weaver.Lint. +15:44:19.021 main < org.aspectj.weaver.Lint. +15:44:19.021 main > org.aspectj.weaver.World. +15:44:19.111 main < org.aspectj.weaver.World. +15:44:19.201 main > org.aspectj.weaver.bcel.BcelWeaver. +15:44:19.201 main < org.aspectj.weaver.bcel.BcelWeaver. +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 +.... -- cgit v1.2.3