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 Logging Practices - Jeff Dever + Commons HttpClient $Id: logging.xml,v 1.12 2004/04/21 04:18:09 mbecke Exp $ -

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");
- 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");
-
+ HttpClient performs two different kinds of logging: the standard + context logging used within each class, and wire logging. +

+ +

+ 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
+
+

+
-