Java troubleshooting tools

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, it lists all Java processes on the system.

This tool can be used to see if PingAuthorize 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 include:

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

Replace <processID> with 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:

Replace <pathToJava> with the path to the Java command from which the core file was created, and replace <pathToCore> with 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.

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. For example:

Some of the additional arguments include:

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 PingAuthorize 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 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. For example:

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. For example:

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

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

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