You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by rd...@apache.org on 2006/02/12 23:02:55 UTC
svn commit: r377251 - in /jakarta/commons/proper/logging/trunk/xdocs:
navigation.xml troubleshooting.xml
Author: rdonkin
Date: Sun Feb 12 14:02:53 2006
New Revision: 377251
URL: http://svn.apache.org/viewcvs?rev=377251&view=rev
Log:
First part of a trouble shooting guide. First cut at explaining how to read diagnostics.
Added:
jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml
Modified:
jakarta/commons/proper/logging/trunk/xdocs/navigation.xml
Modified: jakarta/commons/proper/logging/trunk/xdocs/navigation.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/trunk/xdocs/navigation.xml?rev=377251&r1=377250&r2=377251&view=diff
==============================================================================
--- jakarta/commons/proper/logging/trunk/xdocs/navigation.xml (original)
+++ jakarta/commons/proper/logging/trunk/xdocs/navigation.xml Sun Feb 12 14:02:53 2006
@@ -38,6 +38,8 @@
href="/guide.html"/>
<item name="Tech Guide"
href="/tech.html"/>
+ <item name="Troubleshooting Guide"
+ href="/troubleshooting.html"/>
<item name="Wiki"
href="http://wiki.apache.org/jakarta-commons/Logging"/>
<item name='JavaDoc'
Added: jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml?rev=377251&view=auto
==============================================================================
--- jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml (added)
+++ jakarta/commons/proper/logging/trunk/xdocs/troubleshooting.xml Sun Feb 12 14:02:53 2006
@@ -0,0 +1,211 @@
+<?xml version="1.0"?>
+
+<!--
+
+ Copyright 2006 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+<document>
+
+ <properties>
+ <title>JCL Troubleshooting Guide</title>
+ <author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
+ </properties>
+
+ <body>
+ <section name='Using JCL Diagnostics'>
+ <p>
+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 (<code>LogFactory</code> and <code>LogFactoryImpl</code>).
+ </p>
+ <p>
+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.
+ </p>
+ <subsection name='When To Use Diagnostic Logging'>
+ <p>
+Diagnostic logging is intended only to be used when debugging a problematic
+configuration. It <em>should</em> be switched off for production.
+ </p>
+ </subsection>
+ <subsection name='How To Use Diagnostic logging'>
+ <p>
+Diagnostic logging is controlled through the system property
+<code>org.apache.commons.logging.diagnostics.dest</code>. Setting the property value
+to the special strings <code>STDOUT</code> or <code>STDERR</code> (case-sensitive)
+will output messages to <code>System.out</code> and <code>System.err</code> respectively.
+Setting the property value to a valid file name will result in the messages being logged
+to that file.
+ </p>
+ </subsection>
+ <subsection name='OIDs'>
+ <p>
+Diagnostics uses the concept of an Object ID (OID). This allows the identity of objects
+to be tracked without relying on useful <code>toString</code> implementations.
+These are of the form:
+ </p>
+<code><pre>
+<em>classname</em>@<em>system identity hash code</em>
+</pre></code>
+ <p>
+The <em>system identity hash code</em> is found by calling <code>System.identityHashCode()</code>
+which should uniquely identify a particular instance. The classname is usually the fully qualified
+class name though in a few cases, <code>org.apache.commons.logging.impl.LogFactoryImpl</code> may be
+shorten to <code>LogFactoryImpl</code> to increase ease of reading. For example:
+ </p>
+<code><pre>
+sun.misc.Launcher$AppClassLoader@20120943
+LogFactoryImpl@1671711
+</pre></code>
+ <p>
+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.
+ </p>
+ </subsection>
+ <subsection name='Diagnostic Message Prefix'>
+ <p>
+Each diagnostic message is prefixed with details of the class being logger in a standard format.
+This takes the form:
+ </p>
+<code><pre>
+[<em>class-identifier</em> -> <em>ClassLoader OID</em>]
+</pre></code>
+ <p>
+<em>ClassLoader OID</em> is the <a href='#OIDs'>OID</a> of a classloader which loaded
+the class issuing the message.
+<em>class-identifier</em> identifies the object issuing the message.
+ </p>
+ <p>
+In the case of
+<code>LogFactory</code>, this is just <code>LogFactory</code>. For example (line split):
+ </p>
+<code><pre>
+[LogFactory
+ -> sun.misc.Launcher$AppClassLoader@20120943] BOOTSTRAP COMPLETED
+</pre></code>
+ <p>
+In the case of
+<code>LogFactoryImpl</code>, 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):
+ </p>
+<code><pre>
+[LogFactoryImpl@1671711
+ -> sun.misc.Launcher$AppClassLoader@20120943] Instance created.
+</pre></code>
+ </subsection>
+ <subsection name='ClassLoader Hierarchy Tree'>
+ <p>
+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 <code>getParent</code>.
+Each classloader is represented (visually) by an OID (to allow cross referencing)
+and the relationship indicated in <code><em>child</em> --> <em>parent</em></code> fashion.
+For example (line split for easy reading):
+ </p>
+<code><pre>
+ClassLoader tree:java.net.URLClassLoader@3526198
+ --> sun.misc.Launcher$AppClassLoader@20120943 (SYSTEM)
+ --> sun.misc.Launcher$ExtClassLoader@11126876
+ --> BOOT
+</pre></code>
+ <p>
+Represents a hierarchy with four elements ending in the boot classloader.
+ </p>
+ </subsection>
+ <subsection name='LogFactory Class Bootstrap'>
+ <p>
+Whenever the <code>LogFactory</code> class is initialized, diagnostic messages about
+the classloader environment are logged. The content of each of these messages is prefixed by
+<code>[ENV]</code> to help distinguish them. The extension directories, application classpath,
+details of the classloader (including the <a href='#OIDs'>OID</a> and <code>toString</code>
+value) used to load <code>LogFactory</code> and the
+<a href='#ClassLoader%20Hierarchy%20Tree'>classloader tree</a> for that classloader
+are logged.
+ </p>
+ <p>
+Many Sun classloaders have confusing <code>toString</code> values. For example, the OID may be
+ </p>
+<code><pre>
+sun.misc.Launcher$AppClassLoader@20120943
+</pre></code>
+ <p>
+with a <code>toString</code> value of
+ </p>
+<code><pre>
+sun.misc.Launcher$AppClassLoader@133056f
+</pre></code>
+ <p>
+Other classloader implementations may give very useful information (such as the local classpath).
+ </p>
+ <p>
+Finally, once initialization is complete a <code>BOOTSTRAP COMPLETED</code> message is issued.
+ </p>
+ </subsection>
+ <subsection name='Construction Of LogFactoryImpl Instances'>
+ <p>
+<code>LogFactoryImpl</code> is the standard and default <code>LogFactory</code> implementation.
+This section obviously only applies to configurations using this implementation.
+ </p>
+ <p>
+Before assigning a <code>Log</code> instance, <code>LogFactory</code> loads a
+<code>LogFactory</code> implementation. The content is prefixed by <code>[LOOKUP]</code>
+for each diagnostic message logged by this process.
+ </p>
+ <p>
+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.
+ </p>
+ <p>
+Information of particular interest is logged at this stage. Details of the TCCL are logging
+allowing the <a href='#OIDs'>OID</a> later to be cross-referenced to the <code>toString</code> value
+and the <a href='#ClassLoader%20Hierarchy%20Tree'>classloader tree</a>. For example, the
+following log snippet details the TCCL (lines split):
+ </p>
+<code><pre>
+[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
+</pre></code>
+ </subsection>
+ <subsection name='Log Discovery Diagnostics'>
+ <p>
+The standard <code>LogFactoryImpl</code> issues many diagnostic messages when discovering
+the <code>Log</code> implementation to be used.
+ </p>
+ <p>
+During discovery, environment variables are loaded and values set. This content is prefixed by
+<code>[ENV]</code> to make it easier to distinguish this material.
+ </p>
+ <p>
+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 <code>LogFactory</code> and to the TCCL.
+ </p>
+ </subsection>
+ </section>
+ </body>
+</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org