From 6bf58252543ff7dab3fdb08ea190673755ade549 Mon Sep 17 00:00:00 2001 From: Oleg Kalnichevski Date: Sat, 28 Feb 2009 15:52:03 +0000 Subject: [PATCH] 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 --- src/site/apt/logging.apt | 288 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 src/site/apt/logging.apt diff --git a/src/site/apt/logging.apt b/src/site/apt/logging.apt new file mode 100644 index 000000000..888433e86 --- /dev/null +++ b/src/site/apt/logging.apt @@ -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 +~~ . + + ---------- + 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. <<>> 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 <<>>, 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 <<>> 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 <<>>) + + By implementing some simple interfaces <<>> can be extended to support + basically any other custom logging framework. <<>> tries to automatically + discover the logging framework to use. If it fails to select the expected one, you must + configure <<>> by hand. Please refer to the <<>> + 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 <<>> has a log named + <<>>. Since all classes follow this convention + it is possible to configure context logging for all classes using the single log named + <<>>. + +* 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 + + <<>> can delegate to a variety of loggers for processing the actual output. + Below are configuration examples for <<>>, <<>> and + <<>>. + +** Commons Logging Examples + + <<>> comes with a basic logger called <<>>. This logger writes all + logged messages to <<>>. The following examples show how to configure + <<>> via system properties to use <<>>. It is strongly recommended + to configure <<>> system properties through JVM process arguments at the + start up. + + * Enable header 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 +-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 <<>> is via a <<>> file. <<>> + will automatically read and configure itself using a file named <<>> when + it's present at the root of the application classpath. Below are some <<>> configuration + examples. + + <> <<>> is not included in the <<>> distribution. + + * Enable header 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 +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 <<>> manual is the + best reference for how to configure <<>>. 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 <<>>. 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 <<>> 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 - <> + +-------------------------------------- +.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}}.