Summary

Add the options "incremental", "chunksize=" and "maxfilesize=" to JMap -histo to improve JMap with the ability to dump heap histogram incrementally.

Problem

Now, the "JMap -histo" tool can not dump intermediate result, which is useful if the heap is large and dumping the whole heap can be stuck.

Solution

Add three new command options to control incremental dumping of intermediary data:

• incremental[:<file_name>], enable the incremental dump of heap, dumped data will be saved to , by default it is "IncrementalHisto.dump"

• chunksize=<N>, size of objects (in KB) will be dumped in one chunk.

• maxfilesize=<N>, size of the incremental data dump file (in KB), when data size is larger than maxfilesize, the file is erased and latest data will be written.

Expected behavior:

• Option "incremental[: <file_name>]" option will enable incremental dump, data will be dumped to , default is "IncrementalHisto.dump".

• "chunksize=<N>" determines the size (in KB) of objects to be dumped in one chunk, by default chunksize=2, "chunk" means the unit of data that are dumped to file in one incremental round. e.g. "chunksize=5" means objects will be dumped to file every time the counted objects size reaches to 5KB.

• "maxfilesize=<N>" controls the file size of the incremental dump. by default maxfilesize=5000, if dumped file size is larger than <N>, the previously dumped chunk data will be erased, and latest chunk data will be written to the file.

• if "chunksize" is larger than "maxfilesize", the dumped file only contains the latest dumped chunk data, And the file size is same as chunksize.

• if "incremental" is not specified, "JMap -histo" behaves as before, the whole incremental dump is disabled, value of "chunksize" and "maxfilesize" takes no effect.

• Zero, negative values or values larger than the max of uintx for "chunksize" and "maxfilesize" are not allowed.

• Specify "incremental" will NOT disable full heap histo dump.

Please be aware that this is subset of enhancement of JMap. More detail please refer to https://bugs.openjdk.java.net/browse/JDK-8214535. The corresponding webrev is http://cr.openjdk.java.net/~lzang/jmap-8214535/8215623/.

Specification

Updated specification (here is the new usage chunk, the "incremental", "chunksize" and "maxfilesize" are new):

jmap -clstats <pid> 
    to connect to running process and print class loader statistics 
jmap -finalizerinfo <pid> 
    to connect to running process and print information on objects awaiting finalization 
jmap -histo[:[<histo-options>]] <pid> 
    to connect to running process and print histogram of java object heap 
jmap -dump:<dump-options> <pid> 
    to connect to running process and dump java heap
jmap -? -h --help 
    to print this help message 

dump-options: 
  live        dump only live objects 
  all          dump all objects in the heap (default if one of "live" or "all" is not specified 
  format=b    binary format 
  file=<file>   dump heap to <file> 

Example: jmap -dump:live,format=b,file=heap.bin <pid> 

histo-options: 
  live       count only live objects 
  all         count all objects in the heap (default if one of "live" or "all" is not specified) 
  file=<file> dump data to <file> 
  incremental dump support: 
    incremental[:<file_name>]  enable incremental dump, data will be dumped
                               to <file_name> (default is "IncrementalHisto.dump")
    chunksize=<N>   size in Kilobytes of objects will be dumped in one chunk (default is 2) 
    maxfilesize=<N>    size limit of incremental dump file (in KB, default is 2000)    
    The incremental data file is saved under the same path specified by "file=" option. 
Example:
 jmap -histo:live,file=/tmp/histo.data,incremental:incHisto.dump,chunkcount=2,maxfilesize=5000 <pid>