From 32342824e03b7e01a3e41075d77dcc43176a5815 Mon Sep 17 00:00:00 2001 From: Robert Burrell Donkin Date: Sun, 12 Feb 2006 22:02:53 +0000 Subject: [PATCH] First part of a trouble shooting guide. First cut at explaining how to read diagnostics. git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/logging/trunk@377251 13f79535-47bb-0310-9956-ffa450edef68 --- xdocs/navigation.xml | 2 + xdocs/troubleshooting.xml | 211 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 213 insertions(+) create mode 100644 xdocs/troubleshooting.xml diff --git a/xdocs/navigation.xml b/xdocs/navigation.xml index b1a6421..fd1cf43 100755 --- a/xdocs/navigation.xml +++ b/xdocs/navigation.xml @@ -38,6 +38,8 @@ href="/guide.html"/> + + + + + + + + JCL Troubleshooting Guide + Commons Documentation Team + + + +
+

+Diagnostics is a feature introduced in JCL 1.1 as an aid to debugging problems +with JCL configurations. When diagnostics are switched on, messages are logged +to a stream (specified by the user) by the two main class involved in discovery +JCL (LogFactory and LogFactoryImpl). +

+

+Diagnostics are intended to be used in conjunction with the source. The source +contains numerous and lengthy comments. Often these are intended to help explain +the meaning of the messages. +

+ +

+Diagnostic logging is intended only to be used when debugging a problematic +configuration. It should be switched off for production. +

+ + +

+Diagnostic logging is controlled through the system property +org.apache.commons.logging.diagnostics.dest. Setting the property value +to the special strings STDOUT or STDERR (case-sensitive) +will output messages to System.out and System.err respectively. +Setting the property value to a valid file name will result in the messages being logged +to that file. +

+ + +

+Diagnostics uses the concept of an Object ID (OID). This allows the identity of objects +to be tracked without relying on useful toString implementations. +These are of the form: +

+
+classname@system identity hash code
+
 +

+The system identity hash code is found by calling System.identityHashCode() +which should uniquely identify a particular instance. The classname is usually the fully qualified +class name though in a few cases, org.apache.commons.logging.impl.LogFactoryImpl may be +shorten to LogFactoryImpl to increase ease of reading. For example: +

+
+sun.misc.Launcher$AppClassLoader@20120943
+LogFactoryImpl@1671711
+
 +

+OIDs are intended to be used to cross-reference. They allow particular instances of classloaders +and JCL classes to be tracked in different context's. This plays a vital role in building +up the understanding of the classloader environment required to diagnose JCL problems. +

+ + +

+Each diagnostic message is prefixed with details of the class being logger in a standard format. +This takes the form: +

+
+[class-identifier -> ClassLoader OID]
+
 +

+ClassLoader OID is the OID of a classloader which loaded +the class issuing the message. +class-identifier identifies the object issuing the message. +

+

+In the case of +LogFactory, this is just LogFactory. For example (line split): +

+
+[LogFactory 
+   -> sun.misc.Launcher$AppClassLoader@20120943] BOOTSTRAP COMPLETED
+
 +

+In the case of +LogFactoryImpl, the prefix is the instance OID. This can be cross referenced +to discover the details of the TCCL used to manage this instance. For example (line split): +

+
+[LogFactoryImpl@1671711 
+   -> sun.misc.Launcher$AppClassLoader@20120943] Instance created.
+
 + + +

+Understanding the relationships between classloaders is vital when debugging JCL. +At various points, JCL will print to the diagnostic log the hierarchy for important +classloaders. This is obtained by walking the tree using getParent. +Each classloader is represented (visually) by an OID (to allow cross referencing) +and the relationship indicated in child --> parent fashion. +For example (line split for easy reading): +

+
+ClassLoader tree:java.net.URLClassLoader@3526198  
+      --> sun.misc.Launcher$AppClassLoader@20120943 (SYSTEM) 
+      --> sun.misc.Launcher$ExtClassLoader@11126876 
+      --> BOOT
+
 +

+Represents a hierarchy with four elements ending in the boot classloader. +

+ + +

+Whenever the LogFactory class is initialized, diagnostic messages about +the classloader environment are logged. The content of each of these messages is prefixed by +[ENV] to help distinguish them. The extension directories, application classpath, +details of the classloader (including the OID and toString +value) used to load LogFactory and the +classloader tree for that classloader +are logged. +

+

+Many Sun classloaders have confusing toString values. For example, the OID may be +

+
+sun.misc.Launcher$AppClassLoader@20120943
+
 +

+with a toString value of +

+
+sun.misc.Launcher$AppClassLoader@133056f
+
 +

+Other classloader implementations may give very useful information (such as the local classpath). +

+

+Finally, once initialization is complete a BOOTSTRAP COMPLETED message is issued. +

+ + +

+LogFactoryImpl is the standard and default LogFactory implementation. +This section obviously only applies to configurations using this implementation. +

+

+Before assigning a Log instance, LogFactory loads a +LogFactory implementation. The content is prefixed by [LOOKUP] +for each diagnostic message logged by this process. +

+

+The implementation used can vary per Thread context classloader (TCCL). If this the first time +that a Log has been requested for a particular TCCL a new instance will be created. +

+

+Information of particular interest is logged at this stage. Details of the TCCL are logging +allowing the OID later to be cross-referenced to the toString value +and the classloader tree. For example, the +following log snippet details the TCCL (lines split): +

+
+[LogFactory -> sun.misc.Launcher$AppClassLoader@20120943] 
+    [LOOKUP] LogFactory implementation requested for the first time for context 
+        classloader java.net.URLClassLoader@3526198
+[LogFactory -> sun.misc.Launcher$AppClassLoader@20120943] 
+    [LOOKUP] java.net.URLClassLoader@3526198 == 'java.net.URLClassLoader@35ce36'
+[LogFactory -> sun.misc.Launcher$AppClassLoader@20120943] 
+    [LOOKUP] ClassLoader tree:java.net.URLClassLoader@3526198 
+        --> sun.misc.Launcher$AppClassLoader@20120943 (SYSTEM)  
+          --> sun.misc.Launcher$ExtClassLoader@11126876 
+            --> BOOT
+
 + + +

+The standard LogFactoryImpl issues many diagnostic messages when discovering +the Log implementation to be used. +

+

+During discovery, environment variables are loaded and values set. This content is prefixed by +[ENV] to make it easier to distinguish this material. +

+

+The possible messages issued during discovery are numerous. To understand them, the source +should be consulted. Attention should be paid to the classloader hierarchy trees for the +classloader used to load LogFactory and to the TCCL. +

+ +
+ +