HeapStats

HeapStats is Java troubleshooting tool.
This tool suites of three applications.

• Agent
  • HeapStats JVMTI agent for gathering JavaVM runtime information continuously.
• Analyzer
  • HeapStats JavaFX GUI analyzer for analysis by various graphs.
• CLI
  • HeapStats commandline analyzer.

Also two supplemental applications are available:

• MBean
  • MBean for operating HeapStats Agent via JMX
  • See mbean/README.md for more details
• Attacher
  • Attach JVMTI agent to existing process
  • See agent/attacher/README.md for more details

Agent

Agent gathers various JavaVM runtime information such as the below.

• The amount of instances and total size per live object
• The reference relationship of objects on Java Heap
• Thread condition
• Process information

More detailes are here.

Requirements

• Linux x64 / x86_64 / AArch32
• Oracle JDK / OpenJDK 6u18 or later

NOTE: For JDK 8u262 or later, we recommend to use built-in agent, JDK Flight Recorder, instead of HeapStats

How to use

You can attach HeapStats agent by any way of the following:

• -agentlib:heapstats[=conf]
  • JVM will load libheapstats.so from library path.
  • libheapstats.so should be resolved via LD_LIBRARY_PATH or library path (e.g. /etc/ld.so.conf)
• -agentpath:/path/to/heapstats[=conf]
  • JVM will load libheapstats.so from specified path
• heapstats-attacher
  • Attach to existing process
  • Recommend to use on JDK 8 or earlier
• jcmd <PID> JVMTI.agent_load /path/to/libheapstats.so
  • Attach to existing process
  • JVMTI.agent_load has been introduced in Java 9
  • Recommend to specify with absolute path

Build requirements

• GNU make
• Apache Ant
• GCC
• JDK 7 or later
• Intel TBB
• NetSNMP
• GNU Binutils

See also: HeapStats Builder

Analyzer

Analyzer is GUI application for analyzing data which are collected from Agent.
Also it supports JDP autodiscovery and Error Report Transmission.

Requirements

Linux x64 or Windows x64

How to use

Run <analyzer dir>/bin/heapstats-analyzer (Linux) or <analyzer dir>\bin\heapstats-analyzer.bat (Windows)

JDP

The automatic discovery on JDP (Java Discovery Protocol) can be enabled by the following JVM options.

-Dcom.sun.management.jmxremote.port=<JMX port>
-Dcom.sun.management.jmxremote.authenticate=<true|false>
-Dcom.sun.management.jmxremote.ssl=<true|false>
-Dcom.sun.management.jmxremote.autodiscovery=true

JDP sends a packet per 5 seconds by default. If Analyzer can NOT receive a JDP packet from a monitoring JVM instance, color of its name on the screen will become orange.

Error Report Transmission

Oracle JDK can provide a real-time detection of JVM crash, but OpenJDK DOES NOT support it. In addition, Oracle JDK needs to be run with the following options.

-XX:+TransmitErrorReport
-XX:ErrorReportServer=<address>:<port (4711 by default)>

NOTE: Error Report Transmission has been removed since JDK 12

Build requirements

• Apache Maven
• JDK 13 or later

Add / Create Plugin

HeapStats Analyzer supports custom plugin. See SamplePlugin for details.

CLI

If you want to analyze data which are collected by HeapStats Agent on CUI environment, you can use HeapStats CLI.

Requirements

Linux x64 or Windows x64

How to use

Run <cli dir>/bin/heapstats-cli (Linux) or <cli dir>\bin\heapstats-cli.bat (Windows)

If you want to see options, please run heapstats-cli with -help.

Build requirements

• Apache Maven
• JDK 13 or later

Documents and Binaries

More detailes and released binaries are available on icedtea community: http://icedtea.classpath.org/wiki/HeapStats

Build all

$ configure --with-jdk=/path/to/jdk13
$ make

Testing

• Basic test is agent/test
• Race condition tests are available on race-condition

Contributing

Contribution are most welcome! HeapStats is an open source project under the GNU General Public License, version 2. See CONTRIBUTING.md for details.

License

GNU General Public License, version 2