EclipseLink/Examples/JPA/Logging

How To Configure Logging

This document describes how to configuring logging with EclipseLink JPA. See Logging in the EclipseLink User's Guide for complete information.

Introduction

With EclipseLink JPA you can turn on logging to do the following:

• monitor configuration details
• facilitate debugging
• view the SQL that is being sent to the database

The logging utility is based on the java.util.logging, but is not integrated with java.util.logging by default. This utility provides you with nine levels of logging control over the amount and detail of the log output. Note that, as logging is not part of the JPA specification, the information the log output provides is EclipseLink JPA-specific.

By default the log output goes to System.out or your console. To configure the output to be logged to file the persistence unit property eclipselink.logging.file can be set:

<property name="eclipselink.logging.file" value="output.log"/>

EclipseLink's logging service is plug-able and several different logging integrations are supported including java.util.logging. To enable java.util.logging the persistence unit property eclipselink.logging.logger can be set:

<property name="eclipselink.logging.logger" value="JavaLogger"/>

Log Levels

Level	Description
OFF	This setting disables the generation of the log output. You may want to set logging to OFF during production to avoid the overhead of logging.
SEVERE	This level enables reporting of failure cases only. Usually, if the failure occurs, the application stops.
WARNING	This level enables logging of issues that have a potential to cause problems. For example, a setting that is picked by the application and not by the user.
INFO	This level enables the standard output. The contents of this output is very limited. It is the default logging level if a logging level is not set.
CONFIG	This level enables logging of such configuration details as your database login information and some metadata information. You may want to use the CONFIG log level at deployment time.
FINE	This level enables logging of the first level of the debugging information and SQL. You may want to use this log level during debugging and testing, but not at production.
FINER	This level enables logging of more debugging information than the FINE setting. For example, the transaction information is logged at this level. You may want to use this log level during debugging and testing, but not at production.
FINEST	This level enables logging of more debugging information than the FINER setting, such as a very detailed information about certain features (for example, sequencing). You may want to use this log level during debugging and testing, but not at production.
ALL	This level currently logs at the same level as FINEST.

The logging information accumulates at every sequential log level: each log output includes the information from the output of the previous log level. For example, if you set the log level to INFO, your output will include log messages from INFO, WARNING, and SEVERE levels.

Log Level Configuration

The log level configuration is included in the definition of the persistence unit in the persistence.xml file, as follows:

<property name="eclipselink.logging.level" value="FINE"/>

The logging of SQL parameters can be enabled, or disabled through the following properties:

Disable:

<property name="eclipselink.logging.parameters" value="false"/>

Enable:

<property name="eclipselink.logging.level.sql" value="FINE"/>
<property name="eclipselink.logging.parameters" value="true"/>

Note: Setting eclipselink.logging.level to FINE is not sufficient (as of EclipseLink 2.4.0 - Juno), you have to set eclipselink.logging.level.sql to FINE.

This property will also control how parameters are logged in exceptions. By default parameters are only logged for log level < CONFIG.

Every log output contains various optional details that you can configure using the following properties:

• Print Timestamp — you can set it in the persistence.xml file (see the following example) to determine when a log output was printed. The default value for this setting is true:

<property name="eclipselink.logging.timestamp" value="true"/>

• Print Session — you can set it in the persistence.xml file (see the following example) to determine on which underlying session (if any) the message was sent. This setting is applicable to messages that require a database connection such as SQL, and the transaction information. The default value for this setting is true:

<property name="eclipselink.logging.session" value="true"/>

• Print Thread — you can set it in the persistence.xml file (see the following example) when you are running multithreaded applications to print the hashcode of the thread, which wrote the message. The default value for this setting is false:

<property name="eclipselink.logging.thread" value="false"/>

• Print Exceptions — you can set it in the persistence.xml file (see the following example) to enable logging of the exceptions's messages at the time when these exceptions are thrown. The default value for this setting is true:

<property name="eclipselink.logging.exceptions" value="true"/>

Server Logging

Most Java EE application servers have their own logging. To integrate with an application servers logging set the logger type to,

<property name="eclipselink.logging.logger" value="ServerLogger"/>

This will only work if the ServerPlatform (specified in target-server) that you are using defines a logging integration. If the ServerPlatform doesn't specific this, you can subclass it, or provide your own SessionLog logger.

Some application servers such as WebLogic automatically set the logger property to integrate with their logging. Because of this if you set the log-level in WebLogic it will have no effect, as the log level must be set in WebLogic's logging configuration.

In the default case on WebLogic you will find default INFO logs only in your server log but not on an IDE console redirect.

• a) Out of the box - WebLogic will log default INFO logs to the domain log file only
• b) With the DefaultLogger set - WebLogic will redirect logs to the console and keep logging them to the domain log file until a server restart
• c) After a server restart - application logs will only go to the console if the DefaultLogger is set - otherwise they will only go the the domain log file

If you want to be able to set the log level in EclipseLink, then set the logger type to DefaultLogger,

<property name="eclipselink.logging.logger" value="DefaultLogger"/>

Summary

You can configure logging at various levels to facilitate the debugging of your application. See the Using EclipseLink JPA Extensions for Logging for the complete description of the available extensions.

See also Configuring a custom logger