4.2.8 jheapprof

Synopsis

jheapprof [-i|-f] [-class class-name] [-staticroot|-nostaticroot]
    [-explicit|-noexplicit] [-fullgc|-copygc|-nogc]
    [-garbage|-nogarbage] [-rootobjectinfo|-norootobjectinfo]
    [-rootobjectinfost value] [-force] -p process-ID

Storage location

Application Server installation directory/jdk/jre/bin/

Function

This command outputs an extended thread dump, including statistics by class, about the java process with the process ID specified in the argument.

You can output the size of all instances under the members of each class instance, into an extended thread dump as statistics by class. By outputting statistics multiple times, you can check the change in a Java object size or other information. You can use this information to detect memory leakage.

Execution permission

Execute the command as the same user as the user of the java process specified by the process ID in the arguments.

Arguments

-i

Displays the message confirming the execution of the output processing for an extended thread dump containing the class-wise statistical information. You input either y or n. If you input y, the extended thread dump containing the class-wise statistical information is output. If you input n, no information is output and the processing terminates. Even if you omit this option, the option is valid as long as the -f option is not specified.

-f

Disables the -i option. If you omit this option, the -i option becomes valid.

-class class-name

Creates a list of the classes that include the specified class as a member, and outputs the list within the thread dump.

-staticroot

Enables the reference related information output functionality that is based on the static field and outputs the reference related information based on the static field. If you omit this option, the -nostaticroot option is enabled.

The specification of the -class option is a prerequisite for this option. When you do not specify the -class option, this option is disabled.

If this option is concurrently specified with the -nostaticroot option, the option specified at the end is enabled.

-nostaticroot

Disables the reference related information output functionality based on the static field.

If this option is concurrently specified with the -staticroot option, the option specified at the end is enabled.

-explicit

The Explicit heap is included in the statistics of the instance statistics function. If omitted, this option is enabled unless the -noexplicit option is specified.

Note that if this option and the -noexplicit option are specified concurrently, the option specified last is enabled.

-noexplicit

The Explicit heap is not included in the statistics of the instance statistics function. If it is omitted , this option is enabled as long as -copygc and -nogc option are not specified. If omitted, the -explicit option is enabled.

Note that if this option and the -explicit option are specified concurrently, the option specified last is enabled.

-fullgc

Specifies a full garbage collection for the garbage collection that is to be executed before the statistics is collected. If omitted, this option is enabled unless the -copygc option and -nogc option is specified.

Note that if you concurrently specify this option with the -copygc option or the -nogc option, the option that is specified last is applied.

-copygc

Specifies a copy garbage collection for the garbage collection that is to be executed before the statistics is collected. If this option and the -nogc option are omitted, the -fullgc option is enabled.

Note that if you concurrently specify this option with the -fullgc option or the -nogc option, the option that is specified last is applied.

-nogc

The garbage collection will not be executed before the statistics is collected. If this option and the -copygc option are omitted, the-fullgc option is enabled.

Note that if you concurrently specify this option with the -fullgc option or the -copygc option, the option that is specified last is applied.

-garbage

Enables the unused object statistic function in the Tenured area and outputs the class-wise statistical information for the statistic information of the unused objects to the Tenured area. The instance statistic function and the STATIC member statistic function are disabled. If omitted, the -nogarbage option is enabled.

For the Select pre-statistic garbage collection function, the -fullgc option and the -copygc option are disabled, and the -nogc option is enabled. Consequently, the garbage collection is not executed before the statistics process.

Note that if you specify this option concurrently with the-nogarbage option, the option that is specified last will be applied.

-nogarbage

The unused object statistic function in the Tenured area is disabled. Therefore, the class-wise statistical information is not output for the statistic information of the unused objects to the Tenured area. If omitted, this option is enabled unless you specify the -garbage option.

Note that if you specify this option concurrently with the -garbage option, the option that is specified last will be applied.

-rootobjectinfo

The output functionality of the base object list for increasing the Tenured area is enabled and outputs the base object for increasing the Tenured area.

For this option, you must enable the -garbage option. Also, when you enable the -nogarbage option, this option is disabled. If omitted, this option is enabled unless you specify the -norootobjectinfo option.

Note that if you specify this option concurrently with the -norootobjectinfo option, the option specified last will be applied.

-norootobjectinfo

The base object list output functionality for increasing the Tenured area is disabled. Therefore, the base object list for increasing the Tenured area is not output. If you omit the output of the base object list, the -rootobjectinfo option is enabled.

Note that if you specify this option concurrently with the -rootobjectinfo option, the option specified last will be applied.

-rootobjectinfost value

Controls the volume of the information of the basic object list for increasing the Tenured area. The class information, with the total instance size greater than the specified value, is output to the basic object list for increasing the tenured area.

For this option, you must enable the -rootobjectinfo option. Therefore, when you enable the -norootobjectinfo option, this option is disabled. You can specify a whole number in value. When you specify any number other than a whole number or a character string, the process ends with an error message indicating that there is an error in specifying the argument.

Default value: 0

-force

Requests the output of the extended thread dump for the java process indicated by the process ID specified in the -p option, without confirming the existence of the /tmp/hsperfdata_user-name/process-ID file created in the java process.

-p process-id

Specifies the process ID of the Java program for which the class-wise statistical information is to be output.

Type: Integer

The following values can be specified:

• 0 to 4294967295

Output format

Use the jheapprof commands to output the class-wise statistical information to the extended thread dump. Specify the Java process, where you want to output the class-wise statistical information, and the class, where you want to output the reference-related information, and then execute the jheapprof commands.

You can specify the following when executing the jheapprof command:

• Specify whether to output the information of an Explicit heap as class-wise statistical information.

• Specify whether to execute the garbage collection before acquiring the class-wise statistical information.

• The following shows an example of executing the jheapprof command:

  Here, the class-wise statistical information of Java process with process ID 2463 is output.

  1. In the -p option, specify the process ID of the Java process where you want to output the class-wise statistical information, and then execute the jheapprof command.

     % jheapprof -p 2463

     When the -f option is being omitted in the jheapprof command, the following confirmation message is displayed:

     The confirmation message of process ID is displayed in the following format:

     send SIGQUIT to 2463: ? (y/n)

  2. Enter y.

     An extended thread dump with class-wise statistics is output. The following message is output in the running java program:

     Writing Java core to javacore2463.030806215140.txt... OK

     The running java program creates an extended thread dump with class-wise statistics (javacore.process ID.date-time.txt) in the current directory and continues the program.

• When the information of an Explicit heap is output to the class-wise statistical information

  If the following conditions are satisfied, you can output the information of an Explicit heap to the class-wise statistical information:

  • -XX:+HitachiUseExplicitMemory is specified in the JavaVM start option.

  • Explicit heap is used for implementing the application, or setting the execution environment (J2EE server).

  Specify the -explicit option in the jheapprof command, and then execute the command to output the information of an Explicit heap to the class-wise statistical information.

• When specifying whether to execute the garbage collection

  You can select whether to execute the garbage collection before the class-wise statistical information is output. This functionality is called as pre-statistical garbage collection selection functionality. Specify any of the following options in the jheapprof command, if you want to execute the garbage collection before the class-wise statistical information is output:

  • -fullgc

    Executes the full garbage collection, and then outputs the class-wise statistical information.

  • -copygc

    Executes the copy garbage collection, and then outputs the class-wise statistical information.

  • -nogc

    Outputs the class-wise statistical information without executing the garbage collection.

Exit Status

Exit Status	Explanation
0	The command terminated normally.
1	The command terminated abnormally.
2	There is no response indicating that the output processing has terminated within the fixed time for the class-wise statistical information.

Output messages

If any of the following error or warning messages is output, the extended thread dump with statistics by class is not output.

No.	Error message	Explanation
1	usage: jheapprof [-f|-i] [-class classname] [-staticroot|-nostaticroot] [-explicit|-noexplicit] [-fullgc|-copygc|-nogc] [-garbage|-nogarbage] [-rootobjectinfo|-norootobjectinfo] [-rootobjectinfost size] [-force] -p process-id	An argument specified for the jheapprof command is invalid.
2	jheapprof: illegal option -- option	The indicated option (option) specified in the jheapprof command is invalid.
3	process-id: Now processing previous request, this request canceled	The process indicated by process-id specified in the argument of the jheapprof command is currently engaged in the output of the class-wise statistical information.
4	process-id: No such process	The process indicated by process-id specified in the argument of the jheapprof command is not found or the process indicated by process-id specified in the jheapprof command is not the java process.
5	process-id: Not owner	The user is not the owner of the process indicated by process-id specified in the argument of the jheapprof command.
6	jheapprof: can't create work file at /tmp , this request canceled	If the user does not have permission to reference or write data into the directory for temporary files, the extended thread dump containing the class-wise statistical information cannot be output. The output request for the extended thread dump containing the class-wise statistical information is cancelled.
7	jheapprof: please delete name-of-undeleted-file in full-path-of-undeleted-file	When the jheapprof command terminated, it could not delete an internal file. Delete the indicated file on the indicated full path.
8	jheapprof: unexpected error occurred: error-cause	An unexpected error occurred during jheapprof command execution. The following are examples of causes that may be displayed in error-cause: When work memory could not be allocated: malloc systemcall fail (errno=Y) When an object could not be closed: close systemcall fail (errno=Y)
9	process-id: Timeout occurred. Java process not responding	The process indicated by process-id specified in the argument of the jheapprof command did not return a response indicating that the output processing terminated within the fixed time for the class-wise statistical information.
10	process-id: Failed to retry GC. Java process is GC locked.	The execution of GC by the process process-ID specified in the argument of the jheapprof command is suppressed, so GC could not be executed.

Notes

• The jheapprof command is provided as a utility for program development. You do not use this command in system operations.

• The jheapprof command cannot be executed concurrently for the same java process. Execute the command after the class-wise statistical information is output to the extended thread dump by a previous jheapprof command.

• The jheapprof command sends the SIGQUIT signal to the specified process. If you specify a program other than the java program by mistake, the other program might stop.

• The jheapprof command uses the /tmp/hsperfdata_user-name/process-ID file at runtime. If the applicable file does not exist, the statistical information by the class is not output from the jheapprof command.

• To include the Explicit heap in the statistics of the instance statistical information, you specify -XX:+HitachiUseExplicitMemory, and then specify the -explicit option using the jheapprof command for the java process in which the explicitly managed heap functionality is enabled.

  Note that if -XX:-HitachiUseExplicitMemory is specified and the explicitly managed heap functionality is disabled, even if you specify -explicit, the instance in the Explicit heap will not be included in the statistics of the instance statistical information.