You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by ol...@apache.org on 2009/02/28 16:52:04 UTC
svn commit: r748870 -
/httpcomponents/httpclient/trunk/src/site/apt/logging.apt
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