mbecke 2004/07/05 13:55:53
Modified: httpclient/xdocs Tag: HTTPCLIENT_2_0_BRANCH logging.xml
Log:
Logging guide updates.
PR: 29549
Submitted by: Michael Becke
Reviewed by: Oleg Kalnichevski
Revision Changes Path
No revision
No revision
1.11.2.2 +128 -46 jakarta-commons/httpclient/xdocs/logging.xml
Index: logging.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/logging.xml,v
retrieving revision 1.11.2.1
retrieving revision 1.11.2.2
diff -u -r1.11.2.1 -r1.11.2.2
--- logging.xml 21 Apr 2004 04:17:46 -0000 1.11.2.1
+++ logging.xml 5 Jul 2004 20:55:53 -0000 1.11.2.2
@@ -4,64 +4,146 @@
<properties>
<title>HttpClient Logging Practices</title>
- <author email="[EMAIL PROTECTED]">Jeff Dever</author>
+ <author email="[EMAIL PROTECTED]">Commons HttpClient</author>
<revision>$Id$</revision>
</properties>
<body>
-
<section name="Logging Practices">
<p>
<em>HttpClient</em> utilizes the logging interface provided by the
<a href="http://jakarta.apache.org/commons/logging/";>
- Jakarta Commons Logging</a> package. Commons Logging provides
+ Jakarta Commons Logging</a> package. <em>Commons Logging</em> provides
a simple and generalized
<a href="http://jakarta.apache.org/commons/logging/api/index.html";>
- log interface</a> to various logging packages. By using the
- Commons Logging configuration, HttpClient can be configured
- for a variety of logging behaviours.
- </p><p>
- </p><p>
- There are two specific types of loggers used within
- <em>HttpClient</em>: the standard <code>log</code> used for each
- class and the <code>wireLog</code> used for wire messages.
- Commons Logging allows for various logging systems to do the
- actual output. The most basic is SimpleLog which uses stdout
- to write log messages. All the following examples are shown with
- SimpleLog to highlight the utility within <em>HttpClient</em>
- </p><p>
- <u>log</u><br />
- The logging output can be configured on a class by class basis if
- desired. This is accomplished by setting a system property for
- each class. For example, if you wanted to see extremely detailed
- information on authentication routines, you could turn up the
- logging level for the Authenticator by setting the following
- property:<br />
-
<code>org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient.Authenticator=trace</code><br
/>
- The default log level for all classes can be set to a default by
- using the following:<br />
- <code>org.apache.commons.logging.simplelog.defaultlog=info</code><br />
+ log interface</a> to various logging packages. By using
+ <em>Commons Logging</em>, <em>HttpClient</em> can be configured
+ for a variety of different logging behaviours.
</p><p>
- <u>wireLog</u><br />
- There is one log that cuts across several classes that is used for
- logging wire messages. <i>Careful when turning this on as
- potentially a huge volume of data may be written, some of it in
- binary format.</i><br />
- org.apache.commons.logging.simplelog.log.httpclient.wire=debug
- </p><p>
- When troubleshooting a problem, it is good to turn on the log to find
out
- what is going on, both over the wire and in httpclient. The following
- statements can be used to configure the logger from within your java
- application:
- <blockquote>
- System.setProperty("org.apache.commons.logging.Log",
"org.apache.commons.logging.impl.SimpleLog");<br />
-
System.setProperty("org.apache.commons.logging.simplelog.showdatetime", "true");<br />
-
System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire",
"debug");<br />
-
System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient",
"debug");<br />
- </blockquote>
+ <em>HttpClient</em> performs two different kinds of logging: the
standard
+ context logging used within each class, and wire logging.
+ </p>
+ <subsection name="Context Logging">
+ <p>
+ Context logging contains information about the internal operation
+ of HttpClient as it performs HTTP requests. Each class has its own
+ log named according to the class's fully qualified name. For example
+ the class <code>HttpClient</code> has a log named
+ <code>org.apache.commons.httpclient.HttpClient</code>. Since all
classes
+ follow this convention it is possible to configure context logging for
+ all classes using the single log named
<code>org.apache.commons.httpclient</code>.
</p>
+ </subsection>
+ <subsection name="Wire Logging">
+ <p>
+ The wire log is used to log all data transmitted to and from servers
when
+ executing HTTP requests. This log should only be enabled to debug
problems,
+ as it will produce an extremely large amount of log data, some of it in
binary
+ format.
+ </p>
+ <p>
+ Because the content of HTTP requests is usually less important for
debugging
+ than the HTTP headers, these two types of data have been separated into
+ different wire logs. The content log is
<code>httpclient.wire.content</code>
+ and the header log is <code>httpclient.wire.header</code>.
+ </p>
+ </subsection>
+ </section>
+ <section name="Configuration Examples">
+ <p>
+ <em>Commons Logging</em> can delegate to a variety of loggers for
processing
+ the actual output. Below are configuration examples for <em>Commons
Logging</em>
+ and <em>Log4j</em>.
+ </p>
+ <subsection name="Commons Logging Examples">
+ <p>
+ <em>Commons Logging</em> comes with a basic logger called
+ <code>SimpleLog</code>. This logger writes all logged messages to
+ <code>System.err</code>. The following examples show how to
configure
+ <em>Commons Logging</em> via system properties to use
<code>SimpleLog</code>.
+ </p>
+ <p>
+ <b>Note:</b> The system properties must be set before a reference
to any
+ <em>Commons Logging</em> class is made.
+ </p>
+ <p>
+ <u>Enable header wire + context logging</u> - <b>Best for
Debugging</b><br />
+ <blockquote>
+ System.setProperty("org.apache.commons.logging.Log",
"org.apache.commons.logging.impl.SimpleLog");<br />
+
System.setProperty("org.apache.commons.logging.simplelog.showdatetime", "true");<br />
+
System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire.header",
"debug");<br />
+
System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient",
"debug");<br />
+ </blockquote>
+ </p>
+ <p>
+ <u>Enable full wire(header and content) + context logging</u><br />
+ <blockquote>
+ System.setProperty("org.apache.commons.logging.Log",
"org.apache.commons.logging.impl.SimpleLog");<br />
+
System.setProperty("org.apache.commons.logging.simplelog.showdatetime", "true");<br />
+
System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire",
"debug");<br />
+
System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient",
"debug");<br />
+ </blockquote>
+ </p>
+ <p>
+ <u>Enable just context logging</u><br />
+ <blockquote>
+ System.setProperty("org.apache.commons.logging.Log",
"org.apache.commons.logging.impl.SimpleLog");<br />
+
System.setProperty("org.apache.commons.logging.simplelog.showdatetime", "true");<br />
+
System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient",
"debug");<br />
+ </blockquote>
+ </p>
+ </subsection>
+ <subsection name="Log4j Examples">
+ <p>
+ The simplest way to configure <a
href="http://logging.apache.org/log4j/";>Log4j</a>
+ is via a <i>log4j.properties</i> file. <em>Log4j</em> will
automatically
+ read and configure itself using a file named
<i>log4j.properties</i> when
+ it's present at the root of the application classpath. Below are
some
+ <em>Log4j</em> configuration examples.
+ </p>
+ <p>
+ <b>Note:</b> <em>Log4j</em> is not included in the
<em>HttpClient</em> distribution.
+ </p>
+ <p>
+ <u>Enable header wire + context logging</u> - <b>Best for
Debugging</b><br />
+ <blockquote>
+log4j.rootLogger=INFO, stdout<br />
+<br />
+log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br />
+log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br />
+log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br />
+<br />
+log4j.logger.httpclient.wire.header=DEBUG<br />
+log4j.logger.org.apache.commons.httpclient=DEBUG<br />
+ </blockquote>
+ </p>
+ <p>
+ <u>Enable full wire(header and content) + context logging</u><br />
+ <blockquote>
+log4j.rootLogger=INFO, stdout<br />
+<br />
+log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br />
+log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br />
+log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br />
+<br />
+log4j.logger.httpclient.wire=DEBUG<br />
+log4j.logger.org.apache.commons.httpclient=DEBUG<br />
+ </blockquote>
+ </p>
+ <p>
+ <u>Enable just context logging</u><br />
+ <blockquote>
+log4j.rootLogger=INFO, stdout<br />
+<br />
+log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br />
+log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br />
+log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br />
+<br />
+log4j.logger.org.apache.commons.httpclient=DEBUG<br />
+ </blockquote>
+ </p>
+ </subsection>
</section>
-
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
