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