f8c59c7d27
git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/logging/trunk@382145 13f79535-47bb-0310-9956-ffa450edef68
212 lines
8.5 KiB
XML
212 lines
8.5 KiB
XML
<?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 contexts. 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> from <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
|
|
from 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
|
|
from 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 from sun.misc.Launcher$AppClassLoader@20120943]
|
|
[LOOKUP] LogFactory implementation requested for the first time for context
|
|
classloader java.net.URLClassLoader@3526198
|
|
[LogFactory from sun.misc.Launcher$AppClassLoader@20120943]
|
|
[LOOKUP] java.net.URLClassLoader@3526198 == 'java.net.URLClassLoader@35ce36'
|
|
[LogFactory from 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>
|