| ~~ ==================================================================== |
| ~~ 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://docs.oracle.com/javase/7/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://docs.oracle.com/javase/7/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://docs.oracle.com/javase/7/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 = 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://docs.oracle.com/javase/7/docs/technotes/guides/logging/overview.html} |
| Java Logging documentation}}. |
