Logging Practices

HttpClient utilizes the logging interface provided by the Jakarta Commons Logging package. Commons Logging provides a simple and generalized log interface to various logging packages. By using Commons Logging, HttpClient can be configured for a variety of different logging behaviours.

HttpClient performs two different kinds of logging: the standard context logging used within each class, and wire logging.

Context 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.

Wire Logging

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.

Configuration Examples

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 Examples

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");

Log4j Examples

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

Note that the default configuration for Log4J is very inefficient as it causes all the logging information to be generated but not actually sent anywhere. The Log4J manual is the best reference for how to configure Log4J. It is available at http://logging.apache.org/log4j/docs/manual.html