Java example source code file (logging.apt)

This example source code file (logging.apt) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java tags/keywords

all, apache, by, commons, enable, examples, finest, http, httpclient, info, license, log4j, logging, the

The logging.apt example source code

~~ ====================================================================
~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you 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.
~~ ====================================================================
~~
~~ This software consists of voluntary contributions made by many
~~ individuals on behalf of the Apache Software Foundation.  For more
~~ information on the Apache Software Foundation, please see
~~ <http://www.apache.org/>.

    ----------
    HttpClient Logging Practices
    ----------
    ----------
    ----------

Logging Practices

    Being a library HttpClient is not to dictate which logging framework the user has to use. 
    Therefore  HttpClient utilizes the logging interface provided by the 
    {{{http://commons.apache.org/logging/}Commons Logging}} package. <<> provides 
    a simple and generalized 
    {{{http://commons.apache.org/logging/commons-logging-1.0.4/docs/apidocs/}log interface}} to 
    various logging packages. By using <<>, HttpClient can be configured for a 
    variety of different logging behaviours. That means the user will have to make a choice which 
    logging framework to use. By default <<> supports the following logging 
    frameworks:

    * {{{http://logging.apache.org/log4j/docs/index.html}Log4J}}

    * {{{http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html}
      java.util.logging}}

    * {{{http://commons.apache.org/logging/commons-logging-1.0.4/docs/apidocs/org/apache/commons/logging/impl/SimpleLog.html}
      SimpleLog}} (internal to <<>)

    By implementing some simple interfaces <<> can be extended to support 
    basically any other custom logging framework. <<> tries to automatically 
    discover the logging framework to use. If it fails to select the expected one, you must 
    configure <<> by hand. Please refer to the <<>> 
    documentation for more information.

    HttpClient performs three different kinds of logging: the standard context logging used within 
    each class, HTTP header logging and full 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 <<> has a log named 
    <<>. Since all classes follow this convention 
    it is possible to configure context logging for all classes using the single log named 
    <<>.

* {Wire Logging}

    The wire log is used to log all data transmitted to and from servers when executing HTTP 
    requests. The wire log uses the {{{org.apache.http.wire}}} logging category. This log should 
    only be enabled to debug problems, as it will produce an extremely large amount of log data.
    
* {HTTP header Logging}

    Because the content of HTTP requests is usually less important for debugging than the HTTP 
    headers, the {{{org.apache.http.headers}}} logging category for capturing HTTP headers only.

* {Configuration Examples}

    <<> can delegate to a variety of loggers for processing the actual output. 
    Below are configuration examples for <<>, <<>> and 
    <<>.

** {Commons Logging Examples}

    <<> comes with a basic logger called <<>>. This logger writes all 
    logged messages to <<>. The following examples show how to configure 
    <<> via system properties to use <<>>. It is strongly recommended
    to configure <<> system properties through JVM process arguments at the 
    start up.

    * Enable header wire + context logging - <

--------------------------------------
-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
-Dorg.apache.commons.logging.simplelog.showdatetime=true
-Dorg.apache.commons.logging.simplelog.log.org.apache.http=DEBUG
-Dorg.apache.commons.logging.simplelog.log.org.apache.http.wire=ERROR
--------------------------------------

    * Enable full wire + context logging

--------------------------------------
-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
-Dorg.apache.commons.logging.simplelog.showdatetime=true
-Dorg.apache.commons.logging.simplelog.log.org.apache.http=DEBUG
--------------------------------------

    * Enable context logging for connection management

--------------------------------------
-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
-Dorg.apache.commons.logging.simplelog.showdatetime=true
-Dorg.apache.commons.logging.simplelog.log.org.apache.http.impl.conn=DEBUG
--------------------------------------

    * Enable context logging for connection management / request execution

--------------------------------------
-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
-Dorg.apache.commons.logging.simplelog.showdatetime=true
-Dorg.apache.commons.logging.simplelog.log.org.apache.http.impl.conn=DEBUG
-Dorg.apache.commons.logging.simplelog.log.org.apache.http.impl.client=DEBUG
-Dorg.apache.commons.logging.simplelog.log.org.apache.http.client=DEBUG
--------------------------------------

** {Log4j Examples}

    The simplest way to configure <<> is via a <<>> file. <<>> 
    will automatically read and configure itself using a file named <<> when 
    it's present at the root of the application classpath. Below are some <<> configuration 
    examples.

    < <<>> is not included in the <<>> distribution.              
    
    * Enable header wire + 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.http=DEBUG
log4j.logger.org.apache.http.wire=ERROR
--------------------------------------
 
    * Enable full wire + 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.http=DEBUG
--------------------------------------
 
    * Enable context logging for connection management

--------------------------------------
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.http.impl.conn=DEBUG
--------------------------------------
 
    * Enable context logging for connection management / request execution

--------------------------------------
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.http.impl.conn=DEBUG
log4j.logger.org.apache.http.impl.client=DEBUG
log4j.logger.org.apache.http.client=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 <<> manual is the
    best reference for how to configure <<>. It is available at 
    {{{http://logging.apache.org/log4j/docs/manual.html}
    http://logging.apache.org/log4j/docs/manual.html}}.

** {java.util.logging Examples}

    Since JDK 1.4 there has been a package 
    {{{http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html}
    java.util.logging}} that provides a logging framework similar to <<>. By default it 
    reads a config file from <<<$JAVA_HOME/jre/lib/logging.properties>>> which looks like this
    (comments stripped):
    
--------------------------------------
handlers=java.util.logging.ConsoleHandler
.level=INFO
java.util.logging.FileHandler.pattern = %h/java%u.log
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
com.xyz.foo.level = SEVERE
--------------------------------------

    To customize logging a custom <<> file should be created in the project 
    directory. The location of this file must be passed to the JVM as asystem property. This can be 
    done on the command line like so:

--------------------------------------
$JAVA_HOME/java -Djava.util.logging.config.file=$HOME/myapp/logging.properties
-classpath $HOME/myapp/target/classes com.myapp.Main
--------------------------------------

    Alternatively {{{http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/LogManager.html#readConfiguration(java.io.InputStream)"}
    LogManager#readConfiguration(InputStream)}} can be used to pass it the desired configuration.

    * Enable header wire + context logging - <

--------------------------------------
.level = INFO

handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.ConsoleHandler.level = ALL

org.apache.http.level = FINEST
org.apache.http.wire.level = SEVERE
--------------------------------------
    
    * Enable full wire + context logging

--------------------------------------
.level = INFO

handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.ConsoleHandler.level = ALL

org.apache.http.level = FINEST
--------------------------------------
    
    * Enable context logging for connection management

--------------------------------------
.level = INFO

handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.ConsoleHandler.level = ALL

org.apache.http.impl.conn.level = FINEST
--------------------------------------
    
    * Enable context logging for connection management / request execution

--------------------------------------
.level = INFO

handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.ConsoleHandler.level = ALL

org.apache.http.impl.conn.level = FINEST
org.apache.http.impl.client.level = FINEST
org.apache.http.client.level = FINEST
--------------------------------------

    []
    
    More detailed information is available from the
    {{{"http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html"}
    Java Logging documentation}}.