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.
About this task
You can use logging to assist in troubleshooting problems.
- Logging channels
Note: This topic references one or more of the application
server log files. As a recommended alternative, you 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. You can also use
HPEL in conjunction with your native z/OS® logging facilities. If you are using HPEL, you can access
all of your log and trace information using the LogViewer command-line
tool from your 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
Avoid trouble: The openjpa.Log property is ignored
if it is defined in a container-managed persistence unit that uses
the persistence providers that are provided with the application server.
In this case, you must 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,
you can control the types of logging messages and the amount of logging
messages that are recorded.Note: These logging
functions apply only to OpenJPA and JPA for the application server.
Logging functions that are 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:
Table 1. Mapping
OpenJPA logging levels to application server trace levels. The
mappings of OpenJPA logging levels to trace levels in the application
server are: 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 you are using pureQuery and must
trace calls to the database, you must perform both traces.
The
default logging system accepts the following parameters:
- File: The name of the file to which the application server
logs information. You 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 that is 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.
Avoid trouble: The following procedure only
applies to logging in a client container and standalone Java application.
gotcha
Procedure
- Open the persistence.xml file for
the application that you want to modify.
- Add a property name tag to the XML schema named openjpa.log. For example:
<property name="openjpa.log" .../>
- Add additional parameters. For example:
<property name="openjpa.log" value="DefaultLevel=WARN .../>
Note: To reduce overhead by disabling logging, set the
openjpa.log property to NONE and proceed to Step 5.
- Designate the logging channels and the logging level. For example:
<property name="openjpa.log" value="DefaultLevel=WARN, Runtime=INFO, Tool=INFO" .../>
- 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.