6.3.5 Details of a thread dump

A thread dump is a file to which information about the threads running within a Java process are output.

This subsection describes how to collect a thread dump and discusses the jheapprof command.

Organization of this subsection
(1) How to collect a thread dump
(2) Details of jheapprof (outputs extended thread dump with Hitachi statistics by class)

(1) How to collect a thread dump

To collect a thread dump:

  1. Execute the following command to determine the server process running in the working directory:

    installation-directory\psb\jdk\bin\jps -v

    An example of the result of executing this command is shown below. The line containing SDPManager and working-directory indicates the SDP server. In this example, that SDP server's process ID is 4616.

    3980 Program -Xms40m -Xmx256m
    5216 Jps -Dapplication.home=installation-directory\psb\jdk -Xms8m
    4616 SDPManager -Dsdp.home=working-directory -Dsdp.serverLogging

  2. Execute the following command to collect a thread dump for the SDP server's process ID obtained in step 1:

    installation-directory\psb\jdk\jre\bin\jheapprof -f -p 4616

    This command creates under the working directory a thread dump file named javacoreprocess-ID.date-and-time.txt.

We recommend that you collect around 10 thread dumps at an interval of 3 seconds. By collecting multiple thread dumps, you can check the method processes in chronological order to identify a process that is causing a processing slowdown or is not responding.

When you collect multiple thread dumps, make sure that output of one thread dump is completed before collecting a subsequent thread dump.

(2) Details of jheapprof (outputs extended thread dump with Hitachi statistics by class)

Format:

jheapprof [-i|-f] [-class class-name] [-explicit|-noexplicit] [-fullgc|-copygc|-nogc] -p process-ID

Function:
The jheapprof command outputs an extended thread dump containing Hitachi statistics by class. The Hitachi statistics by class enable you to obtain the sizes of all instances under the members that belong to the instances of each class.
Execution permissions:
None
Prerequisites for command execution:
None
Storage directory:

installation-directory\psb\jdk\jre\bin\

Arguments:
-i
Specifies that the user is to be asked to confirm that this command is to be executed on the process with the specified process ID.
Even if this specification is omitted, this option is effective unless the -f option is specified.
-f
Specifies that the user is not to be asked to confirm that this command is to be executed on the process with the specified process ID.
-class class-name
Specifies that the output to the thread dump is to be as a list member of the structure of the class (instance) specified in class-name. You must enclose the package name of the class in double-quotation marks (").
-explicit
Specifies that an Explicit heap is to be included as a target of the instance statistics function. If this option is specified together with the -noexplicit option, the last option specified takes effect. Note that there is no need to specify this option for the SDP server.
-noexplicit
Specifies that an Explicit heap is not to be included as a target of the instance statistics function. If this option is specified together with the -explicit option, the last option specified takes effect. Note that there is no need to specify this option for the SDP server.
-fullgc
Specifies that a full garbage collection is to be executed before the statistical information is output.
If this option is specified together with the -copygc or -nogc option, the last option specified takes effect.
-copygc
Specifies that a copy garbage collection is to be executed before the statistical information is output.
If this option is specified together with the -fullgc or -nogc option, the last option specified takes effect.
-nogc
Specifies that no garbage collection is to be executed before the statistical information is output.
If this option is specified together with the -fullgc or -copygc option, the last option specified takes effect.
-p process-ID
Specifies the process ID of the Java program for which Hitachi statistics by class are to be output.
Notes:
  • This command cannot be executed more than once for the same Java process. If you want to execute the command more than once for the same Java process, wait until the statistics by class have been output to an extended thread dump by the jheapprof command before executing the command again.
  • When a Java process starts, it uses MailSlot to initialize communication. If this initialization fails, the Java process outputs a message and cancels processing.
  • This command can be executed by a user who is not the owner of the Java process whose process ID is specified in the argument.
Return value:
ValueDescription
0Command terminated normally.
1Command resulted in an error.
2Termination of output processing for the Hitachi statistics by class was not received within the specified amount of time.
Error messages:
When any of the messages listed below is displayed, the extended thread dump with Hitachi statistics by class was not output.
No.Error messageDescription
1usage: jheapprof [-f|-i] [-class classname] [-explicit|-noexplicit] [-fullgc|-copygc|-nogc] [-garbage|-nogarbage] [-rootobjectinfo|-norootobjectinfo] [-rootobjectinfost size] -p process-id jheapprofA specified command argument is invalid.
2jheapprof: illegal option -- optionoption specified in the jheapprof command is invalid.
3process-ID: Now processing previous request, this request canceledThe process with the specified process-ID is currently outputting statistics by class.
40: Not ownerA value of 0 is specified for the process-ID argument in the jheapprof command.
5jheapprof: can't create work file at temporary directory, this request canceledBecause the user does not have permissions to reference or write the directory for temporary files, the user cannot output an extended thread dump with Hitachi statistics by class. The request to output an extended thread dump with Hitachi statistics by class is canceled.
6jheapprof: can't get temporary directory, this request canceledThe directory for temporary files could not be retrieved, so the extended thread dump with Hitachi statistics by class could not be output. The request to output an extended thread dump with Hitachi statistics by class is canceled.
7jheapprof: please delete name-of-file-whose-deletion-failed in full-path-of-file-whose-deletion-failedThe jheapprof command was unable to delete an internal file when it terminated. Delete the file at the indicated full path whose deletion failed.
8jheapprof: unexpected error occurred: cause-of-errorAn unexpected error occurred during execution of the jheapprof command.
cause-of-error displays the reason for the error, such as the following:
  • Allocation of work memory failed:
    malloc systemcall fail (errno=Y)
  • Object close processing resulted in an error:
    close systemcall fail (errno=Y)
9jheapprof: can't communicate with process process-IDCommunication could not be performed due to a communication error in the process with the specified process-ID, or there was no process with the specified process-ID.
10process-ID: Timeout occurred. Java process not respondingCompletion of Hitachi statistics by class output processing for the process with the specified process-ID was not received within the specified amount of time.
Examples:
This example collects an extended thread dump with Hitachi statistics by class from the Java program with process ID 8662:

jheapprof -p 8662

When this command is executed, a confirmation message is displayed asking whether or not the extended thread dump with Hitachi statistics by class is to be output:

Force VM to output HitachiJavaHeapProfile: ? (y/n)

To output the extended thread dump with Hitachi statistics by class, enter Y or y. If you enter any other character, the command terminates without outputting the extended thread dump with Hitachi statistics by class.

Force VM to output HitachiJavaHeapProfile: ? (y/n)y

When an extended thread dump with Hitachi statistics by class is output, the following message is displayed in the Java program that is executing:

Writing Java core to javacore8662.030806215140​.txt... OK

An extended thread dump with the following file name is output to the current directory of the Java program and then execution of the Java program continues:
javacoreprocess-ID.date-and-time.txt