PingDirectory

Java troubleshooting tools

The Java Development Kit provides a number of very useful tools to obtain information about Java applications and diagnosing problems. These tools are not included with the Java Runtime Environment (JRE), so the full Java Development Environment (JDK) should always be installed and used to run the Server.

jps

The jps tool is a Java-specific version of the UNIX ps tool. It can be used to obtain a list of all Java processes currently running and their respective process identifiers. When invoked by a non-root user, it will list only Java processes running as that user. When invoked by a root user, then it lists all Java processes on the system.

This tool can be used to see if the PingDirectory server is running and if a process ID has been assigned to it. This process ID can be used in conjunction with other tools to perform further analysis.

This tool can be run without any arguments, but some of the more useful arguments that include:

  • -v – Includes the arguments passed to the JVM for the processes that are listed.

  • -m – Includes the arguments passed to the main method for the processes that are listed.

  • -l – (lowercase L). Include the fully qualified name for the main class rather than only the base class name.

jstack

The jstack tool is used to obtain a stack trace of a running Java process, or optionally from a core file generated if the JVM happens to crash. A stack trace can be extremely valuable when trying to debug a problem, because it provides information about all threads running and exactly what each is doing at the point in time that the stack trace was obtained.

Stack traces are helpful when diagnosing problems in which the server appears to be hung or behaving slowly. Java stack traces are generally more helpful than native stack traces, because Java threads can have user-friendly names (as do the threads used by the Server), and the frame of the stack trace may include the line number of the source file to which it corresponds. This is useful when diagnosing problems and often allows them to be identified and resolved quickly.

To obtain a stack trace from a running JVM, use the command:

jstack {processID}

where {processID} is the process ID of the target JVM as returned by the jps command. To obtain a stack trace from a core file from a Java process, use the command:

jstack {pathToJava} {pathToCore}

where {pathToJava} is the path to the java command from which the core file was created, and {pathToCore} is the path to the core file to examine. In either case, the stack trace is written to standard output and includes the names and call stacks for each of the threads that were active in the JVM.

In many cases, no additional options are necessary. The "-l" option can be added to obtain a long listing, which includes additional information about locks owned by the threads. The “-m” option can be used to include native frames in the stack trace.

jmap

The jmap tool is used to obtain information about the memory consumed by the JVM. It is very similar to the native pmap tool provided by many operating systems. As with the jstack tool, jmap can be invoked against a running Java process by providing the process ID, or against a core file , like:

jmap {processID}
jmap {pathToJava} {pathToCore}

Some of the additional arguments include:

  • -dump:live,format=b,file=filename – Dump the live heap data to a file that can be examined by the jhat tool

  • -heap – Provides a summary of the memory used in the Java heap, along with information about the garbage collection algorithm in use.

  • -histo:live – Provides a count of the number of objects of each type contained in the heap. If the “:live” portion is included, then only live objects are included; otherwise, the count include objects that are no longer in use and are garbage collected.

jhat

The jhat (Java Heap Analysis Tool) utility provides the ability to analyze the contents of the Java heap. It can be used to analyze a heap dump file, which is generated if the PingDirectory server encounters an out of memory error (as a result of the "-XX:+HeapDumpOnOutOfMemoryError" JVM option) or from the use of the jmap command with the "-dump" option.

The jhat tool acts as a web server that can be accessed by a browser in order to query the contents of the heap. Several predefined queries are available to help determine the types of objects consuming significant amounts of heap space, and it also provides a custom query language (OQL, the Object Query Language) for performing more advanced types of analysis.

The jhat tool can be launched with the path to the heap dump file, like:

jhat /path/to/heap.dump

This command causes the jhat web server to begin listening on port 7000. It can be accessed in a browser at http://localhost:7000 (or http://address:7000 from a remote system). An alternate port number can be specified using the "-port" option, like:

jhat -port 1234 /path/to/heap.dump

To issue custom OQL searches, access the web interface using the URL http://localhost:7000/oql/ (the trailing slash must be provided). Additional information about the OQL syntax may be obtained in the web interface at http://localhost:7000/oqlhelp/.

jstat

The jstat tool is used to obtain a variety of statistical information from the JVM, much like the vmstat utility that can be used to obtain CPU utilization information from the operating system. The general manner to invoke it is as follows:

jstat {type} {processID} {interval}

The {interval} option specifies the length of time in milliseconds between lines of output. The {processID} option specifies the process ID of the JVM used to run the PingDirectory server, which can be obtained by running jps as mentioned previously. The {type} option specifies the type of output that should be provided. Some of the most useful types include:

  • -class – Provides information about class loading and unloading.

  • -compile – Provides information about the activity of the JIT complex.

  • -printcompilation – Provides information about JIT method compilation.

  • -gc – Provides information about the activity of the garbage collector.

  • -gccapacity – Provides information about memory region capacities.