commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mbe...@apache.org
Subject cvs commit: jakarta-commons/httpclient/xdocs logging.xml
Date Mon, 05 Jul 2004 20:55:53 GMT
mbecke      2004/07/05 13:55:53

  Modified:    httpclient/xdocs Tag: HTTPCLIENT_2_0_BRANCH logging.xml
  Log:
  Logging guide updates.
  
  PR: 29549
  Submitted by: Michael Becke
  Reviewed by: Oleg Kalnichevski
  
  Revision  Changes    Path
  No                   revision
  No                   revision
  1.11.2.2  +128 -46   jakarta-commons/httpclient/xdocs/logging.xml
  
  Index: logging.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/xdocs/logging.xml,v
  retrieving revision 1.11.2.1
  retrieving revision 1.11.2.2
  diff -u -r1.11.2.1 -r1.11.2.2
  --- logging.xml	21 Apr 2004 04:17:46 -0000	1.11.2.1
  +++ logging.xml	5 Jul 2004 20:55:53 -0000	1.11.2.2
  @@ -4,64 +4,146 @@
   
      <properties>
         <title>HttpClient Logging Practices</title>
  -      <author email="jsdever@apache.org">Jeff Dever</author>
  +      <author email="commons-httpclient-dev@jakarta.apache.org">Commons HttpClient</author>
         <revision>$Id$</revision>
      </properties>
   
      <body>
  -
         <section name="Logging Practices">
            <p>
               <em>HttpClient</em> utilizes the logging interface provided by
the
               <a href="http://jakarta.apache.org/commons/logging/">
  -            Jakarta Commons Logging</a> package.  Commons Logging provides
  +            Jakarta Commons Logging</a> package.  <em>Commons Logging</em>
provides
               a simple and generalized 
               <a href="http://jakarta.apache.org/commons/logging/api/index.html">
  -            log interface</a> to various logging packages.  By using the
  -            Commons Logging configuration, HttpClient can be configured
  -            for a variety of logging behaviours.
  -         </p><p>
  -         </p><p>
  -            There are two specific types of loggers used within
  -            <em>HttpClient</em>: the standard <code>log</code>
used for each 
  -            class and the <code>wireLog</code> used for wire messages.  
  -            Commons Logging allows for various logging systems to do the
  -            actual output.  The most basic is SimpleLog which uses stdout
  -            to write log messages.  All the following examples are shown with
  -            SimpleLog to highlight the utility within <em>HttpClient</em>
  -         </p><p>
  -            <u>log</u><br />
  -            The logging output can be configured on a class by class basis if
  -            desired.  This is accomplished by setting a system property for
  -            each class.  For example, if you wanted to see extremely detailed 
  -            information on authentication routines, you could turn up the 
  -            logging level for the Authenticator by setting the following 
  -            property:<br />
  -            <code>org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient.Authenticator=trace</code><br
/>
  -            The default log level for all classes can be set to a default by
  -            using the following:<br />
  -            <code>org.apache.commons.logging.simplelog.defaultlog=info</code><br
/>
  +            log interface</a> to various logging packages.  By using
  +            <em>Commons Logging</em>, <em>HttpClient</em> can be
configured
  +            for a variety of different logging behaviours.
            </p><p>
  -            <u>wireLog</u><br />
  -            There is one log that cuts across several classes that is used for
  -            logging wire messages.  <i>Careful when turning this on as 
  -            potentially a huge volume of data may be written, some of it in 
  -            binary format.</i><br />
  -            org.apache.commons.logging.simplelog.log.httpclient.wire=debug
  -         </p><p>
  -            When troubleshooting a problem, it is good to turn on the log to find out
  -            what is going on, both over the wire and in httpclient.  The following
  -            statements can be used to configure the logger from within your java
  -            application:
  -            <blockquote>
  -             System.setProperty("org.apache.commons.logging.Log", "org.apache.commons.logging.impl.SimpleLog");<br
/>
  -             System.setProperty("org.apache.commons.logging.simplelog.showdatetime", "true");<br
/>
  -             System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire",
"debug");<br />
  -             System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient",
"debug");<br />
  -            </blockquote>
  +            <em>HttpClient</em> performs two different kinds of logging: the
standard
  +            context logging used within each class, and wire logging.            
  +         </p>
  +         <subsection name="Context Logging">
  +         <p>
  +            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 <code>HttpClient</code> has a log named 
  +            <code>org.apache.commons.httpclient.HttpClient</code>.  Since all
classes
  +            follow this convention it is possible to configure context logging for 
  +            all classes using the single log named <code>org.apache.commons.httpclient</code>.
            </p>
  +         </subsection>
  +         <subsection name="Wire Logging">
  +         <p>
  +            The wire log is used to log all data transmitted to and from servers when
  +            executing HTTP requests.  This log should only be enabled to debug problems,
  +            as it will produce an extremely large amount of log data, some of it in binary
  +            format.
  +         </p>
  +         <p>
  +            Because the content of HTTP requests is usually less important for debugging

  +            than the HTTP headers, these two types of data have been separated into 
  +            different wire logs.  The content log is <code>httpclient.wire.content</code>

  +            and the header log is <code>httpclient.wire.header</code>.
  +         </p>
  +         </subsection>
  +      </section>
  +      <section name="Configuration Examples">
  +          <p>
  +             <em>Commons Logging</em> can delegate to a variety of loggers
for processing 
  +             the actual output.  Below are configuration examples for <em>Commons
Logging</em> 
  +             and <em>Log4j</em>.
  +          </p>
  +          <subsection name="Commons Logging Examples">
  +              <p>
  +                 <em>Commons Logging</em> comes with a basic logger called

  +                 <code>SimpleLog</code>.  This logger writes all logged messages
to 
  +                 <code>System.err</code>. The following examples show how to
 configure 
  +                 <em>Commons Logging</em> via system properties to use <code>SimpleLog</code>.
  +              </p>
  +              <p>
  +                <b>Note:</b> The system properties must be set before a reference
to any 
  +                <em>Commons Logging</em> class is made.              
  +              </p>
  +              <p>
  +                <u>Enable header wire + context logging</u> - <b>Best
for Debugging</b><br />
  +                <blockquote>
  +                 System.setProperty("org.apache.commons.logging.Log", "org.apache.commons.logging.impl.SimpleLog");<br
/>
  +                 System.setProperty("org.apache.commons.logging.simplelog.showdatetime",
"true");<br />
  +                 System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire.header",
"debug");<br />
  +                 System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient",
"debug");<br />
  +                </blockquote>
  +              </p>          
  +              <p>
  +                <u>Enable full wire(header and content) + context logging</u><br
/>
  +                <blockquote>
  +                 System.setProperty("org.apache.commons.logging.Log", "org.apache.commons.logging.impl.SimpleLog");<br
/>
  +                 System.setProperty("org.apache.commons.logging.simplelog.showdatetime",
"true");<br />
  +                 System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire",
"debug");<br />
  +                 System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient",
"debug");<br />
  +                </blockquote>
  +              </p>
  +              <p>
  +                <u>Enable just context logging</u><br />
  +                <blockquote>
  +                 System.setProperty("org.apache.commons.logging.Log", "org.apache.commons.logging.impl.SimpleLog");<br
/>
  +                 System.setProperty("org.apache.commons.logging.simplelog.showdatetime",
"true");<br />
  +                 System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient",
"debug");<br />
  +                </blockquote>
  +             </p>          
  +          </subsection>
  +          <subsection name="Log4j Examples">
  +            <p>
  +                The simplest way to configure <a href="http://logging.apache.org/log4j/">Log4j</a>

  +                is via a <i>log4j.properties</i> file.  <em>Log4j</em>
will automatically 
  +                read and configure itself using a file named <i>log4j.properties</i>
when 
  +                it's present at the root of the application classpath.  Below are some

  +                <em>Log4j</em> configuration examples.
  +            </p>
  +              <p>
  +                <b>Note:</b> <em>Log4j</em> is not included in
the <em>HttpClient</em> distribution.              
  +              </p>
  +              <p>
  +                <u>Enable header wire + context logging</u> - <b>Best
for Debugging</b><br />
  +                <blockquote>
  +log4j.rootLogger=INFO, stdout<br />
  +<br />
  +log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br />
  +log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br />
  +log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br />
  +<br />
  +log4j.logger.httpclient.wire.header=DEBUG<br />
  +log4j.logger.org.apache.commons.httpclient=DEBUG<br />
  +                </blockquote>
  +              </p>          
  +              <p>
  +                <u>Enable full wire(header and content) + context logging</u><br
/>
  +                <blockquote>
  +log4j.rootLogger=INFO, stdout<br />
  +<br />
  +log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br />
  +log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br />
  +log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br />
  +<br />
  +log4j.logger.httpclient.wire=DEBUG<br />
  +log4j.logger.org.apache.commons.httpclient=DEBUG<br />
  +                </blockquote>
  +              </p>
  +              <p>
  +                <u>Enable just context logging</u><br />
  +                <blockquote>
  +log4j.rootLogger=INFO, stdout<br />
  +<br />
  +log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br />
  +log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br />
  +log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br />
  +<br />
  +log4j.logger.org.apache.commons.httpclient=DEBUG<br />
  +                </blockquote>
  +             </p>          
  +          </subsection>
         </section>
  -
      </body>
   
   </document>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message