Ported logging guide from HttpClient 3.x
git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@748870 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Oleg Kalnichevski
parent
d3389a9b7b
commit
6bf5825254
|
|
@ -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}}.
|
||||
Loading…
Reference in New Issue