Monday, March 24, 2008

Debugging HTTPClient

Oracle HTTPClient extensively logs activity during setup and communication. This page provides some tips for enabling logging in HTTPClient.

HTTPClient versions 10.1.2 & earlier

HTTPClient versions 10.1.2. and earlier used a proprietary logging mechanism.

To enable all logging, set the "HTTPClient.log.mask" system property to "-1"

HTTPClient versions 10.1.3 & later

HTTPClient versions 10.1.3 and later uses the standard JDK java.util.logging package.

By default, HTTPClient is enabled by the JDK java.util.logging properties specified at JVM startup. This is describe in the JavaDoc for java.util.logging.LogManager. Usually the JDK logging properties are configured in "/lib/".

Additionally, HTTPClient logging may be enabled using System Properties. Set the "HTTPClient.log.level" System Property to one of the valid java.util.logging.Level values. See Log Levels, below.

Log Levels

HTTPClient only uses the trace portion of the JDK logging levels. This is because HTTPClient is a utility library, and is unaware of the application context within which an error occurs.

For example, consider the occurrence of a connection loss. A financial application may log a connection loss as SEVERE. A server-monitoring application may log a connection loss as INFO. Since the severity depends on the application context, HTTPClient internally only logs messages at trace levels (CONFIG and lower), and expects the application to log exceptions as appropriate for the application.

The following list indicates the HTTPClient usage of java.util.logging.Level:

* SEVERE - Not used by HTTPClient (v11 & up), reserved for application
* WARNING - Not used by HTTPClient (v11 & up), reserved for application
* INFO - Not used by HTTPClient (v11 & up), reserved for application
* CONFIG - System properties and other configuration data
* FINE - Exceptions and other error conditions
* FINER - Warnings
* FINEST - Informational logging

* ALL - Everything logged in HTTPClient is visible at this level

If the version of HTTPClient is 11 and later, verbose logging may be enabled. To enable verbose mode, set the Java System Property "HTTPClient.log.verbose=true".

Verbose logging adds the following fields to the logging output:

* Log Entry Date
* Logger Name - Usually the class name where the log entry occurred
* Log Level - Per java.util.logging.Level
* Exception Stack Trace

In iAS Installation

HTTPClient logging in iAS is effectively the same as standalone, except for the way Java System Properties are set. HTTPClient logging is directed to system out, which is written to one of the iAS logs.

To set the HTTPClient logging System Properties, following these steps:

1. Open the file $ORACLE_HOME/opmn/conf/opmn.xml
2. Search for the OC4J process whose id matches that of the OC4J instance where you want to enable HTTPClient logging

For example:

3. Set the HTTPClient logging System Properties in the value attribute of the element "java-options", under the element "start-parameters"
4. Start the OC4J instance
5. Review the HTTPClient log where the iAS installation writes the System Out. This log may be "$ORACLE_HOME/opmn/logs/OC4J~<>~default_island~1"

Thanks to Alex Kosowski for providing latest version of this information.

No comments: