hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject svn commit: r748870 - /httpcomponents/httpclient/trunk/src/site/apt/logging.apt
Date Sat, 28 Feb 2009 15:52:04 GMT
Author: olegk
Date: Sat Feb 28 15:52:03 2009
New Revision: 748870

URL: http://svn.apache.org/viewvc?rev=748870&view=rev
Log:
Ported logging guide from HttpClient 3.x

Added:
    httpcomponents/httpclient/trunk/src/site/apt/logging.apt   (with props)

Added: httpcomponents/httpclient/trunk/src/site/apt/logging.apt
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/site/apt/logging.apt?rev=748870&view=auto
==============================================================================
--- httpcomponents/httpclient/trunk/src/site/apt/logging.apt (added)
+++ httpcomponents/httpclient/trunk/src/site/apt/logging.apt Sat Feb 28 15:52:03 2009
@@ -0,0 +1,288 @@
+~~ $HeadURL:$
+~~ $Revision:$
+~~ $Date:$
+~~
+~~ ====================================================================
+~~ 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. <<<Commons
Logging>>> 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 <<<Commons Logging>>>, 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 <<<Commons Logging>>> 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 <<<Commons Logging>>>)
+
+    By implementing some simple interfaces <<<Commons Logging>>> can be
extended to support 
+    basically any other custom logging framework. <<<Commons Logging>>>
tries to automatically 
+    discover the logging framework to use. If it fails to select the expected one, you must

+    configure <<<Commons Logging>>> by hand. Please refer to the <<<Commons
Logging>>> 
+    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 <<<DefaultHttpClient>>> has a log named 
+    <<<org.apache.http.impl.client.DefaultHttpClient>>>. Since all classes
follow this convention 
+    it is possible to configure context logging for all classes using the single log named

+    <<<org.apache.http.impl.client>>>.
+
+* 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
+
+    <<<Commons Logging>>> can delegate to a variety of loggers for processing
the actual output. 
+    Below are configuration examples for <<<Commons Logging>>>, <<<Log4j>>>
and 
+    <<<java.util.logging>>>.
+
+** 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>>>.
It is strongly recommended
+    to configure <<<Commons Logging>>> system properties through JVM process
arguments at the 
+    start up.
+
+    * Enable header wire + context logging - <<Best for Debugging>>
+
+--------------------------------------
+-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 <<<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.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 <<<Log4J>>>
manual is the
+    best reference for how to configure <<<Log4J>>>. 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 <<<Log4J>>>.
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 <<<logging.properties>>> 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 - <<Best for Debugging>>
+
+--------------------------------------
+.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 = ERROR
+--------------------------------------
+    
+    * 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}}.

Propchange: httpcomponents/httpclient/trunk/src/site/apt/logging.apt
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message