Logging applications with JPA

Logging supports viewing, tracing, and troubleshooting the runtime behavior of an application. Java Persistence API (JPA) provides a flexible logging system that is integrated with the application server to assist you in troubleshooting problems.

We can use logging to assist in troubleshooting problems.

• Logging channels

• Logging levels

• Logging in the application server

• Logging in a client container and standalone Java application

Logging channels

This topic references one or more of the application server log files. As a recommended alternative, we can configure the server to use the High Performance Extensible Logging (HPEL) log and trace infrastructure instead of using SystemOut.log , SystemErr.log, trace.log, and activity.log files on distributed and IBM i systems. We can also use HPEL in conjunction with the native z/OS logging facilities. If we are using HPEL, we can access all of the log and trace information using the LogViewer command-line tool from the server profile bin directory. See the information about using HPEL to troubleshoot applications for more information on using HPEL.

In additional to the channels used by OpenJPA, a trace group named openjpa enables channels that are prefixed with "openjpa." Specifying "openjpa" for a trace group overrides any other trace group specification that is specific to a channel; for example:

openjpa.Runtime=debug:openjpa.jdbc.SQL=all
     openjpa=all

The openjpa.Log property is ignored if it is defined in a container-managed persistence unit that uses the persistence providers provided with the application server. In this case, use the standard trace specification for the application server.gotcha

OpenJPA and JPA for WebSphere Application Server implement logging channels to which message data, trace data, and debugging data can be recorded to a configurable repository. The JPA component creates the logging channel at run time and assigns a channel name for identification. The component writes information to the configured repository through the channel. OpenJPA and JPA for WebSphere Application Server create the following channels:

• openjpa.Tools - Command line and Ant server tools

• openjpa.MetaData - Metadata information

• openjpa.Enhance - Enhancement and runtime class generation

• openjpa.Runtime - Messages generated during run time

• openjpa.Query - Query information

• openjpa.DataCache - L2 data cache plug-in information

• openjpa.jdbc.JDBC - JDBC connection information

• openjpa.jdbc.SQL- Detailed SQL execution statements and information

• openjpa.jdbc.SQLDiag- Additional SQL diagnostic information for the entity operations create, retrieve, update, and delete.

• openjpa.jdbc.Schema- Details about operations on the database schema

• wsjpa.pdq- Trace of all interactions between store manager and PDQ run time

• wsjpa.Sqlgen- Diagnostic trace for wsdbgen program

Logging levels

Each of the logging channels use logging levels to control which messages are recorded. The following logging levels are supported by the JPA architecture:

• TRACE - the most detailed option

• INFO - information related to the specific channel

• WARN - warning messages

• ERROR - error condition messages

• FATAL - fatal condition messages

By using a particular logging channel together with logging levels, we can control the types of logging messages and the amount of logging messages that are recorded.

These logging functions apply only to OpenJPA and JPA for the application server. Logging functions provided in implementations of a third-party persistence provider are not covered. However, if the logging output from a third-party persistence provider is directed to the Java System.out or System.err file output streams, the messages are handled by the environment accordingly at run time.

Logging in the application server (container-managed persistence)

The default JPA persistence provider that is supported by the application server records messages and tracing data that are automatically integrated into the RAS component. Alternatively, OpenJPA implements a custom logger to route messages from OpenJPA channels to the channels of the application server.

The channel names that are supported by OpenJPA are used as the trace group names in the trace level for the application server. The mappings of OpenJPA logging levels to trace levels in the application server are:

OpenJPA logging levels to application server trace levels. The mappings of OpenJPA logging levels to trace levels in the application

OpenJPA logging level	Trace level for the application server
TRACE	debug
INFO	info
WARN	warning
ERROR	error
FATAL	fatal

Logging in a client container and standalone Java application (application-managed persistence)

OpenJPA logging uses the basic logging framework and output format:

millis [persistence-unit name]level[thread identifier] channel - message

.

Important: When using IBM Optim™ PureQuery Run time, the PDQ store manager also uses JDBC in some situations, such as for large result set processing. When tracing all calls to the database, you must trace both JDBC and PDQ.

For example:

property name="wsjpa.Log" value="SQL=TRACE"/

This traces the SQL and input parameter values.

property name="wsjpa.Log" value="pdq=TRACE, JDBC=TRACE"/

This performs a detailed trace of calls to the IBM Optim PureQuery Runtime and any calls to JDBC. If we are using pureQuery and must trace calls to the database, perform both traces.

The default logging system accepts the following parameters:

• File: The name of the file to which the application server logs information. We can also use standard output stdout or standard error stderr to send messages. By default, JPA sends log messages to standard error.

• DefaultLevel: The default logging level for channels that are not configured. The values can be TRACE, INFO, WARN, and ERROR. The default setting is INFO.

• DiagnosticContext: A string placed at the beginning of all log messages. If a DiagnosticContext is not supplied and an openjpa.Id property is available, the openjpa.Id value is used.

• <channel>: The channel that is being logged. This parameter can be used to configure the logging level of the channel.

The following procedure only applies to logging in a client container and standalone Java application.gotcha

1. Open the persistence.xml file for the application to modify.

2. Add a property name tag to the XML schema named openjpa.log. For example:
   <property name="openjpa.log" .../>

3. Add additional parameters. For example:
   <property name="openjpa.log" value="DefaultLevel=WARN .../>

   To reduce overhead by disabling logging, set the openjpa.log property to NONE and proceed to Step 5.

4. Designate the logging channels and the logging level. For example:
   <property name="openjpa.log" value="DefaultLevel=WARN, Runtime=INFO, Tool=INFO" .../>

5. Save changes to the file.

Results

The next time the application is started the JPA component logs all channels at the WARN logging level and the Runtime and Tool channels at the INFO level.

What to do next

OpenJPA supports the substitution of other logging methods. Read the logging section of the Apache OpenJPA User Guide for more information and examples.

Subtopics

• Enable enhanced tracing for JPA
  In some situations the trace information generated by the Java Persistence API (JPA) providers shipped with WebSphere Application Server might not be adequate to diagnose a problem. In these situations, an extended trace mechanism can be enabled to generate additional information in the trace file. Extended trace can function only with IBM-shipped persistence providers. It does not work with third-party providers, including alternate versions of OpenJPA bundled within an application or configured as a shared library.

• Enable Enhanced Tracing for JPA in a Java SE environment
  In some cases it might be necessary to run a Java Persistence API (JPA) trace from a Java SE environment.

Related tasks

Task overview: Storing and retrieving persistent data with the JPA API