Diagnostics for Java

Many of the usual sources of CICS diagnostic information contain information that applies to Java applications. In addition to the information supplied by CICS, there are a number of interfaces specific to the JVM that you can use for problem determination.

CICS diagnostic tools for Java

CICS has statistics and monitoring data that you can collect on running Java applications. When errors occur, transactions abend and messages are written to the appropriate log. See CICS messages for a list of the abends and messages that apply to the JVM (SJ) domain. Messages related to Java are in the format DFHSJxxxx.

You can also turn on tracing to produce additional diagnostic information. The trace points for the JVM domain are listed in JVM domain trace points.

When the first JVM is started in a CICS region after initialization, CICS issues message DFHSJ0207, showing the version of Java that is being used.

The Java SDK provides diagnostic tools and interfaces that give you more detailed information about what is happening in the JVM. Messages and diagnostic information from the JVM are written to the stderr log file for the JVM. If you encounter a Java problem, always consult this file. For example, if CICS issues a message to indicate that the JVM has abended, the stderr log file is the primary source of diagnostic information. Controlling the location for JVM output, logs, dumps and trace tells you how to control the location of output from the JVM, and how to redirect messages from JVM internals and output from Java applications running in a JVM.

When you develop Java applications for CICS, it is important to consider the requirements for thread safety and transaction isolation in CICS. If a Java application works correctly on its first use, but does not behave correctly on subsequent uses, then the problem is likely to be due to isolation issues.

OSGi diagnostic files

The OSGi framework produces diagnostic files in zFS that you can use to help troubleshoot problems with OSGi bundles and services in a JVM server:

OSGi cache: The OSGi cache is in the $WORK_DIR/applid/jvmserver/configuration/org.eclipse.osgi directory of the JVM server. $WORK_DIR is the working directory of the JVM server, applid is the CICS APPLID, and jvmserver is the name of the JVMSERVER resource. The OSGi cache contains framework metadata and other information that is required to run the framework. The cache is replaced when the JVM server starts up.
OSGi logs: If an error occurs in the OSGi framework, an OSGi log is created in the $WORK_DIR/applid/jvmserver/configuration/ directory of the JVM server. The file extension is .log.

JVM diagnostic tools

The CICS documentation provides information about some of the Java diagnostic tools and interfaces:

Activating and managing tracing for JVM servers describes how you can use the component tracing provided by the CETR transaction to trace the life cycle of the JVM server and the tasks running inside it. JVM servers do not use auxiliary or GTF tracing. Instead, the tracing is written to a file on zFS that is uniquely named for each JVM server.
Debugging a Java application describes how you can use a remote debugger to step through the application code for a Java application that is running in a JVM. CICS also provides a set of interception points (or plug-in) in the CICS Java middleware, which allows additional Java programs to be inserted immediately before and after the application Java code is run, for debugging, logging, or other purposes. For more information, see The CICS JVM plug-in mechanism.

Many more diagnostic tools and interfaces are available for the JVM. See IBM SDK for z/OS, Java Technology Edition, Version 7, Troubleshooting and support section for information about further facilities that can be used for problem determination for JVMs. The following facilities provide useful diagnostic information:

The internal trace facility of the JVM can be used directly, without going through the interfaces provided by CICS. For information about the system properties that you can use to control the internal trace facility and to output JVM trace information to various destinations, see Using CICS trace. You can use these system properties to output trace from any method or class within the JVM, and to find the value of any parameters and return types on the method call.
If you experience memory leaks in the JVM, you can request a heap dump from the JVM. A heap dump generates a dump of all the live objects (objects still in use) that are in the heap of the JVM. You can also analyze memory leaks using the IBM Health Center and Memory Analyzer tools, which are both available with IBM Support Assistant. For more information about Java tools, see IBM Monitoring and Diagnostic Tools for Java - Health Center.
The HPROF profiler, that is shipped with the IBM® 64-bit SDK for z/OS, Java Technology Edition, provides performance information for applications that run in the JVM, so you can see which parts of a program are using the most memory or processor time.
The JVM provides interfaces for monitoring, profiling, and RAS (Reliability, Availability, and Serviceability).

With all interfaces, options, or system properties available for the IBM JVM that are not specific to the CICS environment, use the IBM JVM documentation as the primary source of information.