Index: xdocs/logging.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/logging.xml,v
retrieving revision 1.12
diff -u -r1.12 logging.xml
--- xdocs/logging.xml 21 Apr 2004 04:18:09 -0000 1.12
+++ xdocs/logging.xml 3 Jul 2004 17:29:00 -0000
@@ -4,64 +4,146 @@
HttpClient utilizes the logging interface provided by the - Jakarta Commons Logging package. Commons Logging provides + Jakarta Commons Logging package. Commons Logging provides a simple and generalized - log interface to various logging packages. By using the - Commons Logging configuration, HttpClient can be configured - for a variety of logging behaviours. -
-
- There are two specific types of loggers used within
- HttpClient: the standard log used for each
- class and the wireLog 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 HttpClient
-
- log
- 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:
- org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient.Authenticator=trace
- The default log level for all classes can be set to a default by
- using the following:
- org.apache.commons.logging.simplelog.defaultlog=info
+ log interface to various logging packages. By using
+ Commons Logging, HttpClient can be configured
+ for a variety of different logging behaviours.
- wireLog
- There is one log that cuts across several classes that is used for
- logging wire messages. Careful when turning this on as
- potentially a huge volume of data may be written, some of it in
- binary format.
- org.apache.commons.logging.simplelog.log.httpclient.wire=debug
-
- 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: -
- System.setProperty("org.apache.commons.logging.Log", "org.apache.commons.logging.impl.SimpleLog");+ HttpClient performs two different kinds of logging: the standard + context logging used within each class, and wire logging. + +
- System.setProperty("org.apache.commons.logging.simplelog.showdatetime", "true");
- System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire", "debug");
- System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient", "debug");
-
+ 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 HttpClient has a log named
+ org.apache.commons.httpclient.HttpClient. Since all classes
+ follow this convention it is possible to configure context logging for
+ all classes using the single log named org.apache.commons.httpclient.
+ 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. +
+
+ 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 httpclient.wire.content
+ and the header log is httpclient.wire.header.
+
+ Commons Logging can delegate to a variety of loggers for processing + the actual output. Below are configuration examples for Commons Logging + and Log4j. +
+
+ Commons Logging comes with a basic logger called
+ SimpleLog. This logger writes all logged messages to
+ System.err. The following examples show how to configure
+ Commons Logging via system properties to use SimpleLog.
+
+ Note: The system properties must be set before a reference to any + Commons Logging class is made. +
+
+ Enable header wire + context logging - Best for Debugging
+
+ System.setProperty("org.apache.commons.logging.Log", "org.apache.commons.logging.impl.SimpleLog");+ +
+ System.setProperty("org.apache.commons.logging.simplelog.showdatetime", "true");
+ System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire.header", "debug");
+ System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient", "debug");
+
+ Enable full wire(header and content) + context logging
+
+ System.setProperty("org.apache.commons.logging.Log", "org.apache.commons.logging.impl.SimpleLog");+ +
+ System.setProperty("org.apache.commons.logging.simplelog.showdatetime", "true");
+ System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire", "debug");
+ System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient", "debug");
+
+ Enable just context logging
+
+ System.setProperty("org.apache.commons.logging.Log", "org.apache.commons.logging.impl.SimpleLog");+ +
+ System.setProperty("org.apache.commons.logging.simplelog.showdatetime", "true");
+ System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient", "debug");
+
+ The simplest way to configure Log4j + is via a log4j.properties file. Log4j will automatically + read and configure itself using a file named log4j.properties when + it's present at the root of the application classpath. Below are some + Log4j configuration examples. +
++ Note: Log4j is not included in the HttpClient distribution. +
+
+ Enable header wire + context logging - Best for Debugging
+
+log4j.rootLogger=INFO, stdout+ +
+
+log4j.appender.stdout=org.apache.log4j.ConsoleAppender
+log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
+log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n
+
+log4j.logger.httpclient.wire.header=DEBUG
+log4j.logger.org.apache.commons.httpclient=DEBUG
+
+ Enable full wire(header and content) + context logging
+
+log4j.rootLogger=INFO, stdout+ +
+
+log4j.appender.stdout=org.apache.log4j.ConsoleAppender
+log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
+log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n
+
+log4j.logger.httpclient.wire=DEBUG
+log4j.logger.org.apache.commons.httpclient=DEBUG
+
+ Enable just context logging
+
+log4j.rootLogger=INFO, stdout+ +
+
+log4j.appender.stdout=org.apache.log4j.ConsoleAppender
+log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
+log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n
+
+log4j.logger.org.apache.commons.httpclient=DEBUG
+