In some situations the trace information generated by the 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 backup 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 JVM. The trace
agent can be enabled using the Administration console by following these steps:
- In the navigation pane expand Servers and click on Application
Servers.
- In the server list pane click on 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 expand Java and Process
Management and click on Process Definition.
- Under the Additional Properties heading expand 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 expand Troubleshooting and click on Logs
and Trace.
- Click on the name of the server to trace.
- Under the General Properties heading click on Diagnostic 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 click on 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.
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 catagories 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. |
- 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.