Configuring Logging in Oracle Application Express Listener 2.0.1

Simple Logging

The easiest way to turn logging on in Listener 2.0.1 is to use Oracle SQL Developer to turn on the debug.debugger setting:

• Launch SQL Developer
• Select View|APEX Listener from the main menu
• Right click on Listener and choose Connect...
• Choose an existing connection or create a new connection
• Enter the credentials for the Listener Administrator user
• In the tree view naviagate to the Listener>Administration>Global Settings>Environment>Error Reporting node. Tick the Show debug messages on the console option.
• Click the Upload button from the toolbar (5th from left), and click yes to confirm the upload.
• The changes will immediately take effect on the Listener instance

Alternatively if your prefer you can edit the defaults.xml Listener configuration file directly. Adding the following to the file to enable logging:

 <entry key="debug.debugger">true</entry>

You must restart the Listener instance after editing defaults.xml manually.

Displaying logging information on the Error Page

Listener can be configured to display the log information in the error page that is displayed whenever an error occurs. This is very useful in development environments for quickly seeing why a request failed. Note it must not be enabled in production environments, because the logging information will likely reveal sensitive information.

To enable this setting using SQL Developer:

• Launch SQL Developer
• Select View|APEX Listener from the main menu
• Right click on Listener and choose Connect...
• Choose an existing connection or create a new connection
• Enter the credentials for the Listener Administrator user
• In the tree view naviagate to the Listener>Administration>Global Settings>Environment>Error Reporting node. Tick the Show error messages in the browser option.
• Click the Upload button from the toolbar (5th from left), and click yes to confirm the upload.
• The changes will immediately take effect on the Listener instance

Alternatively if your prefer you can edit the defaults.xml Listener configuration file directly. Adding the following to the file to enable logging:

 <entry key="debug.printDebugToScreen">true</entry>

You must restart the Listener instance after editing defaults.xml manually.

Advanced Logging

If just logging debug messages to the console is not appropriate for your environment (perhaps you need your logs formatted to a particular standard, or you need to configure log file rotation policies), then you can configure how Listener logs messages via the standard Java Logging Service (java.util.logging) provided by the Java runtime.

Disable debug.debugger if using Java Logging

The debug.debugger=true setting takes precedence over the Java Logging Service. If debug.debugger=true then the detailed diagnostic messages produced when processing a request will be logged directly to the console rather than being forwarded to the Java Logging Service. Therefore it is recommended that when you using the Java Logging Service to set debug.debugger=false or remove the debug.debugger setting from defaults.xml

Configuring Logging output in Standalone Mode

The rest of this post will concentrate on configuring logging when running in Standalone Mode, subsequent posts will describe adapting the techniques described below to work in WebLogic and GlassFish environments.

The JRE logging service is configured via a standard properties file typically named: logging.properties, below is a simple example that logs everything to the console, and logs all classes at the most verbose level:

# Log messages to the console only
handlers=java.util.logging.ConsoleHandler

# Set the logging level of the root logger.
# Levels from lowest to highest are
# FINEST, FINER, FINE, CONFIG, INFO, WARNING and SEVERE.
# The default level for all loggers and handlers is INFO.
.level=FINEST

# Tell the Console Handler to log ALL messages
java.util.logging.ConsoleHandler.level=ALL

Configuring Standalone Mode to use logging.properties

Any JRE can have it’s logging service configured via the java.util.logging.config.file system property, the value of the property being the path to the logging.properties file. Assume logging.properties is located in /usr/local/apex/listener/conf, then you would tell the Listener to use this file as follows:

java -Djava.util.logging.config.file=/usr/local/apex/listener/conf/logging.properties -jar apex.war

If you try this using the sample configuration file shown above, you will see a huge volume of information printed to the console. Log messages for all java components involved in processing a request will appear in the console, including messages from: Grizzly, the embedded web server used in Standalone Mode, the Oracle JDBC Driver, and the Oracle Universal Connection Pool library, amongst others.

There is so much information logged that it becomes almost impossible to focus on the information that we're actually interested in, so let's re-configure logging.properties to focus in on reporting messages from the Listener only, while still letting us know if an error occurs in any of the other components:

# Log messages to the console only
handlers=java.util.logging.ConsoleHandler

# Set non Listener code to log errors only 
.level=SEVERE

# Tell the Console Handler to log ALL messages
java.util.logging.ConsoleHandler.level=ALL

# Set Listener code to log all messages
oracle.dbtools.level=FINEST

Now if you try the above configuration you will notice a lot of information will still be logged, but it's focused on messages produced by the Listener so it's easier to follow, it's a very similar level of information to that produced by the debug.debugger=true setting.

For production environments you will likely want to reduce the verbosity of the logs even further, typically to only report warning or error conditions, so change the oracle.dbtools.level setting as follows:

# ... rest of configuration file as before ...

# Set Listener to only report warning error conditions
oracle.dbtools.level=WARNING

If you want to log to a file instead of the console change the handlers setting, and add the extra settings required for a file logger:

# Log messages to file only
handlers=java.util.logging.FileHandler
# specify the log file name
java.util.logging.FileHandler.pattern=listener.log
# Ensure the log file uses UTF-8
java.util.logging.FileHandler.encoding=UTF-8
# Log messages as plain text, rather than XML
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter

# Set non Listener code to log errors only 
.level=SEVERE

# Tell the File Handler to log ALL messages
java.util.logging.FileHandler.level=ALL

# Set Listener code to log all messages
oracle.dbtools.level=FINEST

If you want to log to both a file and the console you can do something like the following:

# Log messages to file only
handlers=java.util.logging.FileHandler, java.util.logging.ConsoleHandler

# specify the log file name
java.util.logging.FileHandler.pattern=listener.log
# Ensure the log file uses UTF-8
java.util.logging.FileHandler.encoding=UTF-8
# Log messages as plain text, rather than XML
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter


# Set non Listener code to log errors only 
.level=SEVERE

# set the log file to record everything, console to report errors only
java.util.logging.ConsoleHandler.level=SEVERE
java.util.logging.FileHandler.level=ALL

# Set Listener code to log all messages
oracle.dbtools.level=FINEST

Further Reading

For more information on the Java Logging Framework see: The JDK logging documentation.
The java.util.logging.FileHandler log handler has several more configuration options not shown in these examples (such as configuring file rotation) see here for more information.