/usr/share/doc/libcommons-httpclient-java/docs/logging.html is in libcommons-httpclient-java-doc 3.1-14.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>HttpClient - HttpClient Logging Practices</title><style type="text/css" media="all">
@import url("./style/maven-base.css");
@import url("./style/maven-theme.css");@import url("./style/project.css");</style><link rel="stylesheet" href="./style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta><meta name="author" content="HttpComponents Team"></meta><meta name="email" content="httpcomponents-dev@jakarta.apache.org"></meta></head><body class="composite"><div id="banner"><a href="http://jakarta.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src=""></img></a><a href="http://jakarta.apache.org/httpcomponents/httpclient-3.x/" id="projectLogo"><img alt="HttpClient" src="./images/httpclient_logo.png"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">Last published: 18 August 2007
<span class="separator">|</span> Doc for 3.1
</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuOverview"><h5>Overview</h5><ul><li class="none"><a href="features.html">Features</a></li><li class="none"><a href="news.html">News</a></li><li class="none"><a href="status.html">Status</a></li><li class="none"><a href="downloads.html">Download</a></li><li class="none"><a href="http://wiki.apache.org/jakarta-httpclient/" class="externalLink" title="External Link">Wiki</a></li><li class="expanded"><a href="userguide.html">User Guide</a><ul><li class="none"><a href="authentication.html">Authentication Guide</a></li><li class="none"><a href="charencodings.html">Character Encodings</a></li><li class="none"><a href="cookies.html">Cookies</a></li><li class="none"><a href="exception-handling.html">Exception Handling</a></li><li class="none"><strong><a href="logging.html">Logging Guide</a></strong></li><li class="none"><a href="methods.html">Methods</a></li><li class="none"><a href="performance.html">Optimization Guide</a></li><li class="none"><a href="preference-api.html">Preference Architecture</a></li><li class="none"><a href="redirects.html">Redirects Handling</a></li><li class="none"><a href="http://svn.apache.org/viewvc/jakarta/httpcomponents/oac.hc3x/trunk/src/examples/" class="externalLink" title="External Link">Sample Code</a></li><li class="none"><a href="sslguide.html">SSL Guide</a></li><li class="none"><a href="threading.html">Threading</a></li><li class="none"><a href="troubleshooting.html">Trouble Shooting</a></li><li class="none"><a href="tutorial.html">Tutorial</a></li></ul></li><li class="none"><a href="developerguide.html">Developer Guide</a></li></ul></div><div id="menuProject_Documentation"><h5>Project Documentation</h5><ul><li class="none"><a href="index.html">About</a></li><li class="collapsed"><a href="project-info.html">Project Info</a></li><li class="collapsed"><a href="maven-reports.html">Project Reports</a></li><li class="none"><a href="development-process.html">Development Process</a></li></ul></div><div id="legend"><h5>Legend</h5><ul><li class="externalLink">External Link</li><li class="newWindow">Opens in a new window</li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="./images/logos/mavenlogo_builtby_w.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Logging_Practices"></a><h2>Logging Practices</h2>
<p>
Being a library HttpClient is not to dictate which logging framework
the user has to use. Therefore <em>HttpClient</em> utilizes the logging
interface provided by the
<a href="http://commons.apache.org/logging/" class="externalLink" title="External Link">
Commons Logging</a> package. <em>Commons Logging</em> provides
a simple and generalized
<a href="http://commons.apache.org/logging/commons-logging-1.0.4/docs/apidocs/" class="externalLink" title="External Link">
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. That means the user will have
to make a choice which logging framework to use. By default <em>Commons Logging</em>
supports the following logging frameworks:
<ul>
<li><a href="http://logging.apache.org/log4j/docs/index.html" class="externalLink" title="External Link">Log4J</a></li>
<li><a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html" class="externalLink" title="External Link">
java.util.logging</a></li>
<li><a href="http://commons.apache.org/logging/commons-logging-1.0.4/docs/apidocs/org/apache/commons/logging/impl/SimpleLog.html" class="externalLink" title="External Link">
SimpleLog</a> (internal to <em>Commons Logging</em>)</li>
</ul>
By implementing some simple interfaces <em>Commons Logging</em> can be extended to support
basically any other custom logging framework.
<em>Commons Logging</em> tries to automatically discover the logging framework to use. If it
fails to select the expected one, you must configure <em>Commons Logging</em> by hand. Please
refer to the <em>Commons Logging</em> documentation for more information.
</p><p>
<em>HttpClient</em> performs two different kinds of logging: the standard
context logging used within each class, and wire logging.
</p>
<div class="subsection"><a name="Context_Logging"></a><h3>Context Logging</h3>
<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>
</div>
<div class="subsection"><a name="Wire_Logging"></a><h3>Wire Logging</h3>
<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>
</div>
</div><div class="section"><a name="Configuration_Examples"></a><h2>Configuration Examples</h2>
<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>,
<em>Log4j</em> and <em>java.util.logging</em>.
</p>
<div class="subsection"><a name="Commons_Logging_Examples"></a><h3>Commons Logging Examples</h3>
<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></br>
<blockquote>
System.setProperty("org.apache.commons.logging.Log", "org.apache.commons.logging.impl.SimpleLog");<br></br>
System.setProperty("org.apache.commons.logging.simplelog.showdatetime", "true");<br></br>
System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire.header", "debug");<br></br>
System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient", "debug");<br></br>
</blockquote>
</p>
<p>
<u>Enable full wire(header and content) + context logging</u><br></br>
<blockquote>
System.setProperty("org.apache.commons.logging.Log", "org.apache.commons.logging.impl.SimpleLog");<br></br>
System.setProperty("org.apache.commons.logging.simplelog.showdatetime", "true");<br></br>
System.setProperty("org.apache.commons.logging.simplelog.log.httpclient.wire", "debug");<br></br>
System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient", "debug");<br></br>
</blockquote>
</p>
<p>
<u>Enable just context logging</u><br></br>
<blockquote>
System.setProperty("org.apache.commons.logging.Log", "org.apache.commons.logging.impl.SimpleLog");<br></br>
System.setProperty("org.apache.commons.logging.simplelog.showdatetime", "true");<br></br>
System.setProperty("org.apache.commons.logging.simplelog.log.org.apache.commons.httpclient", "debug");<br></br>
</blockquote>
</p>
</div>
<div class="subsection"><a name="Log4j_Examples"></a><h3>Log4j Examples</h3>
<p>
The simplest way to configure <a href="http://logging.apache.org/log4j/" class="externalLink" title="External Link">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></br>
<blockquote>
log4j.rootLogger=INFO, stdout<br></br>
<br></br>
log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br></br>
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br></br>
log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br></br>
<br></br>
log4j.logger.httpclient.wire.header=DEBUG<br></br>
log4j.logger.org.apache.commons.httpclient=DEBUG<br></br>
</blockquote>
</p>
<p>
<u>Enable full wire(header and content) + context logging</u><br></br>
<blockquote>
log4j.rootLogger=INFO, stdout<br></br>
<br></br>
log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br></br>
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br></br>
log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br></br>
<br></br>
log4j.logger.httpclient.wire=DEBUG<br></br>
log4j.logger.org.apache.commons.httpclient=DEBUG<br></br>
</blockquote>
</p>
<p>
<u>Log wire to file + context logging</u><br></br>
<blockquote>
log4j.rootLogger=INFO<br></br>
<br></br>
log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br></br>
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br></br>
log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br></br>
<br></br>
log4j.appender.F=org.apache.log4j.FileAppender<br></br>
log4j.appender.F.File=wire.log<br></br>
log4j.appender.F.layout=org.apache.log4j.PatternLayout<br></br>
log4j.appender.F.layout.ConversionPattern =%5p [%c] %m%n<br></br>
<br></br>
log4j.logger.httpclient.wire=DEBUG, F<br></br>
log4j.logger.org.apache.commons.httpclient=DEBUG, stdout<br></br>
</blockquote>
</p>
<p>
<u>Enable just context logging</u><br></br>
<blockquote>
log4j.rootLogger=INFO, stdout<br></br>
<br></br>
log4j.appender.stdout=org.apache.log4j.ConsoleAppender<br></br>
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout<br></br>
log4j.appender.stdout.layout.ConversionPattern=%5p [%c] %m%n<br></br>
<br></br>
log4j.logger.org.apache.commons.httpclient=DEBUG<br></br>
</blockquote>
</p>
<p>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 <a href="http://logging.apache.org/log4j/docs/manual.html" class="externalLink" title="External Link">http://logging.apache.org/log4j/docs/manual.html</a>
</p>
</div>
<div class="subsection"><a name="java_util_logging_Examples"></a><h3>java.util.logging Examples</h3>
<p>
Since JDK 1.4 there has been a package
<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html" class="externalLink" title="External Link">
java.util.logging</a> that provides a
logging framework similar to <em>Log4J</em>. By default it reads a config file from
<code>$JAVA_HOME/jre/lib/logging.properties</code> which looks like this
(comments stripped):
<blockquote>
handlers=java.util.logging.ConsoleHandler<br></br>
.level=INFO<br></br>
java.util.logging.FileHandler.pattern = %h/java%u.log<br></br>
java.util.logging.FileHandler.limit = 50000<br></br>
java.util.logging.FileHandler.count = 1<br></br>
java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter<br></br>
java.util.logging.ConsoleHandler.level = INFO<br></br>
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter<br></br>
com.xyz.foo.level = SEVERE<br></br>
</blockquote>
To customize logging a custom <code>logging.properties</code> file should be created
in the project directory. The location of this file must be passed to the JVM as a
system property. This can be done on the command line like so:
<blockquote>
$JAVA_HOME/java -Djava.util.logging.config.file=$HOME/myapp/logging.properties
-classpath $HOME/myapp/target/classes com.myapp.Main
</blockquote>
Alternatively
<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/LogManager.html#readConfiguration(java.io.InputStream)" class="externalLink" title="External Link">
LogManager#readConfiguration(InputStream)</a> can be used to pass it the desired
configuration.
</p>
<p>
<u>Enable header wire + context logging</u> - <b>Best for Debugging</b><br></br>
<blockquote>
.level=INFO<br></br>
<br></br>
handlers=java.util.logging.ConsoleHandler<br></br>
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter<br></br>
<br></br>
httpclient.wire.header.level=FINEST<br></br>
org.apache.commons.httpclient.level=FINEST<br></br>
</blockquote>
</p>
<p>
<u>Enable full wire(header and content) + context logging</u><br></br>
<blockquote>
.level=INFO<br></br>
<br></br>
handlers=java.util.logging.ConsoleHandler<br></br>
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter<br></br>
<br></br>
httpclient.wire.level=FINEST<br></br>
org.apache.commons.httpclient.level=FINEST<br></br>
</blockquote>
</p>
<p>
<u>Enable just context logging</u><br></br>
<blockquote>
.level=INFO<br></br>
<br></br>
handlers=java.util.logging.ConsoleHandler<br></br>
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter<br></br>
<br></br>
org.apache.commons.httpclient.level=FINEST<br></br>
</blockquote>
</p>
<p>
More detailed information is available from the
<a href="http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html" class="externalLink" title="External Link">
Java Logging documentation</a>.
</p>
</div>
</div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2001-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
|