In some situations the trace information generated by the Java Persistence API (JPA) providers shipped
with WebSphere® Application Server may 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 will only function with IBM-shipped
persistence providers. It will not work with 3rd party providers,
including versions of OpenJPA bundled within an application or configured
as a shared library.
About this task
Enabling enhanced tracing in a WebSphere Application
Server environment
Enhanced JPA tracing for an application
running on WebSphere Application Server can be enabled
with a few simple steps using wsadmin scripting or the administration
console. The steps below describe how to configure enhanced tracing
using the administration console. This process changes server settings
so it is good practice to back up your server configuration before
proceeding.
Procedure
- Enable the trace agent. A trace agent must be
enabled per application server by passing an argument to the server Java virtual machine (JVM). The trace agent
can be enabled using the Administration console by following these
steps:
- In the navigation pane, select Servers.
Select Application Servers.
- In the server list pane, select the server that needs
the enhanced JPA trace. If multiple servers provide JPA functionality
to your application, these steps must be followed for every server.
- Under the Server Infrastructure heading, select Java
and Process Management. Select Process Definition.
- Under the Additional Properties heading, select Java
virtual machine.
- Add the following argument to the Generic JVM arguments
field, where <WAS install path> is the fully qualified path
of your application server install directory. Make sure to use the
path separator character appropriate for your operating system.
-javaagent:<WASinstall path>/optionalLibraries/IBM/wsjpa/wsjpatrace.jar
- Enable additional trace components and adjust trace file
options. You can accomplish this with wsadmin scripting
or the Administration Console. These steps describe how to adjust
trace file settings and enable components using the Administration
Console:
- In the navigation pane, select Troubleshooting.
Click Logs and Trace.
- Select the name of the server to trace.
- Under the General Properties heading, selectDiagnostic
Trace.
- Make sure Enable Log is checked
and optionally increase the Maximum File Size and Maximum Number of
Historical Files. Depending on the number of additional trace categories
and the trace levels chosen, the trace file can become extremely large.
- Under the Additional Properties heading, select Change
Log Detail Levels.
Important: The
use of generic JVM arguments in the Administrative console does not
currently support spaces within arguments. If spaces are specified
in this field, the server may fail to start. This is more likely to
occur in a Windows® environment because
the default install path is C:\Program Files\IBM\WebSphere\AppServer,
which contains a space in the path. To work around this problem in
a Windows environment use an abbreviated path
name for the <WAS install path>. For example, C:\Progra~1\IBM\WebSphere|AppServer.
On Unix-type systems a symbolic link can be used to eliminate spaces
in the <WAS install path>. For example, if the WebSphere Application
Server installation path is /opt/WAS Install/AppServer,
a symbolic link can be created in /opt from WAS Install to WASInstall,
eliminating the space. Then, specify /opt/WASInstall/AppServer as
the <WAS install path> in the generic JVM argument.
- Enable various extended trace categories by specifying
one or more trace categories from the table below. An example trace
string is: *=info:JPA=all:openjpa.*=finer:openjpa.kernel=finest.
Extended trace traces at the FINER or FINEST trace levels. The FINEST
level includes more detail than FINER. When ALL is specified, extended
trace traces at the FINEST level.
Table 1. Trace categories. Back up your server configuration before you enable enhanced
tracing.
Category |
Relevant trace levels |
Description |
JPA |
OFF, ALL, FINER, FINEST |
Adds extended trace to the JPA trace group. |
openjpa.* |
OFF, ALL, FINER, FINEST |
Normal OpenJPA trace in addition to extended
trace for all categories in OpenJPA when extended trace is enabled. |
openjpa.xtrace.* |
OFF, ALL, FINER, FINEST |
Extended trace for all categories in OpenJPA
when extended trace is enabled. |
openjpa.xtrace.Jdbc |
OFF, ALL, FINER, FINEST |
Extended trace for OpenJPA JDBC classes when
extended trace is enabled. |
openjpa.xtrace.Lib |
OFF, ALL, FINER, FINEST |
Extended trace for OpenJPA library classes when
extended trace is enabled. |
openjpa.xtrace.Persist |
OFF, ALL, FINER, FINEST |
Extended trace for OpenJPA persistence classes
when extended trace is enabled. |
openjpa.xtrace.Kernel |
OFF, ALL, FINER, FINEST |
Extended trace for OpenJPA kernel classes when
extended trace is enabled. |
openjpa.xtrace.General |
OFF, ALL, FINER, FINEST |
Extended trace for OpenJPA classes not included
in the JDBC, Lib, Persist, or Kernel categories when extended trace
is enabled. |
openjpa.xtrace.ApiSpi |
OFF, ALL, FINER, FINEST |
Extended trace for public API/SPI interfaces
defined for WsJPA, OpenJPA and JPA when extended trace is enabled. |
- Save the application server configuration and restart the
application server.
Results
After you restart the application server, the new trace settings
are picked up.
What to do next
Note: Tracing can degrade performance significantly and should
be disabled when not in use. To disable trace, remove the Generic
JVM argument and any trace detail levels added for enhanced tracing.