Enable Enhanced Tracing for Java Persistence API (JPA)

In some situations the trace information generated by the JPA providers shipped with WAS 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.

Enable enhanced tracing in a WAS environment

Enhanced JPA tracing for an application running on WAS 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 the server configuration before proceeding.

 

1. Enable the trace agent. A trace agent must be enabled per appserver by passing an argument to the server JVM. The trace agent can be enabled using the Administration console by following these steps:

   1. In the navigation pane, select Servers. Select Application Servers.

   2. In the server list pane, select the server that needs the enhanced JPA trace. If multiple servers provide JPA functionality to the application, these steps must be followed for every server.

   3. Under the Server Infrastructure heading, select Java and Process Management. Select Process Definition.

   4. Under the Additional Properties heading, select Java virtual machine.

   5. Add the following argument to the Generic JVM arguments field, where <WAS install path> is the fully qualified path of the application server install directory. Make sure to use the path separator character appropriate for the operating system.

      -javaagent:<WASinstall path>/optionalLibraries/IBM/wsjpa/wsjpatrace.jar
      

2. Enable additional trace components and adjust trace file options.

   We 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:

   1. In the navigation pane, select Troubleshooting. Click Logs and Trace.

   2. Select the name of the server to trace.

   3. Under the General Properties heading, selectDiagnostic Trace.

   4. 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.

   5. Under the Additional Properties heading, select Change Log Detail Levels.

      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 WAS 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.

   6. 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

      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.

3. Save the appserver configuration and restart the application server.

 

Results

After you restart the appserver, the new trace settings are picked up.

 

Next steps

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.

 

Related tasks

Logging with the Java Persistence API (JPA) and the appserver