Logging Practices

Being a library HttpClient is not to dictate which logging framework the user has to use. Therefore HttpClient utilizes the logging facade provided by the Apache Log4j 2 package. Log4j 2 provides a simple and generalized log interface to various logging packages. By using Log4j, HttpClient can be configured for a variety of different logging behaviours. That means the user will have to make a choice which logging implementation to use. By default Log4j 2 supports the following logging implementation:

  • Log4J 2
  • SLF4J
  • SimpleLog (internal to Log4J 2)
  • java.util.logging

    By implementing some simple interfaces Log4J 2 can be extended to support basically any other custom logging framework. Log4J 2 tries to automatically discover the logging framework to use. If it fails to select the expected one, you must configure Log4J 2 by hand. Please refer to the Log4J 2 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.

Understanding Logger Names

Most logging implementations use a hierarchical scheme for matching logger names with logging configuration. In this scheme, the logger name hierarchy is represented by '.' characters in the logger name, in a fashion very similar to the hierarchy used for Java package names. For example, org.apache.logging.appender and org.apache.logging.filter both have org.apache.logging as their parent. In most cases, applications name their loggers by passing the current class's name to LogManager.getLogger(...).

Context Logging

Context logging contains information about the internal operation of HttpClient as it performs HTTP requests. Each class has its own logger named according to the class's fully qualified name. For example the class DefaultHttpClient has a logger 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 logger named org.apache.hc.client5.http.

Wire Logging

The wire logger is used to log all data transmitted to and from servers when executing HTTP requests. The wire logger uses the org.apache.hc.client5.http.wire logger name. This logger 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, use the org.apache.hc.client5.http.headers logger for capturing HTTP headers only.

Configuration Examples

Log4j 2 can delegate to a variety of logging implementations for processing the actual output. Below are configuration examples for Log4j 2, Commons Logging, and java.util.logging.

Log4j 2 Examples

The simplest way to configure Log4j 2 is via a log4j2.xml file. Log4j 2 will automatically configure itself using a file named log4j2.xml when it's present at the root of the application classpath. Below are some Log4j configuration examples.

Note: The Log4j 2 implementation a.k.a "core" is not included in the HttpClient distribution. You can include it in your project using Maven, Ivy, Gradle, or SBT.

  • Enable header wire + context logging - Best for Debugging
    <Configuration>
      <Appenders>
        <Console name="STDOUT">
          <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
        </Console>
      </Appenders>
      <Loggers>
        <Logger name="org.apache.hc.client5.http" level="DEBUG">
          <AppenderRef ref="Console"/>
        </Logger>
        <Logger name="org.apache.hc.client5.http.wire" level="DEBUG">
          <AppenderRef ref="Console"/>
        </Logger>
        <Root level="INFO">
          <AppenderRef ref="STDOUT" />
        </Root>
      </Loggers>
    </Configuration>
  • Enable full wire + context logging
    <Configuration>
      <Appenders>
        <Console name="STDOUT">
          <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
        </Console>
      </Appenders>
      <Loggers>
        <Logger name="org.apache.hc.client5.http" level="DEBUG">
          <AppenderRef ref="Console"/>
        </Logger>
        <Root level="INFO">
          <AppenderRef ref="STDOUT" />
        </Root>
      </Loggers>
    </Configuration>
  • Enable context logging for connection management
    <Configuration>
      <Appenders>
        <Console name="STDOUT">
          <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
        </Console>
      </Appenders>
      <Loggers>
        <Logger name="org.apache.hc.client5.http.impl.io" level="DEBUG">
          <AppenderRef ref="Console"/>
        </Logger>
        <Logger name="org.apache.hc.client5.http.impl.nio" level="DEBUG">
          <AppenderRef ref="Console"/>
        </Logger>
        <Root level="INFO">
          <AppenderRef ref="STDOUT" />
        </Root>
      </Loggers>
    </Configuration>
  • Enable context logging for connection management / request execution
    <Configuration>
      <Appenders>
        <Console name="STDOUT">
          <PatternLayout pattern="%d %-5level [%logger] %msg%n%xThrowable" />
        </Console>
      </Appenders>
      <Loggers>
        <Logger name="org.apache.hc.client5.http.impl" level="DEBUG">
          <AppenderRef ref="Console"/>
        </Logger>
        <Root level="INFO">
          <AppenderRef ref="STDOUT" />
        </Root>
      </Loggers>
    </Configuration>

The Log4J 2 manual is the best reference for how to configure Log4J 2. It is available at https://logging.apache.org/log4j/2.x/manual/.