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](mbean/README.md) for more details
* Attacher
    * Attach JVMTI agent to existing process
    * See [agent/attacher/README.md](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](http://icedtea.classpath.org/wiki/HeapStats/information_to_be_collected).

## 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](https://github.com/HeapStats/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](https://github.com/HeapStats/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](agent/test)
* Race condition tests are available on [race-condition](https://github.com/HeapStats/race-condition)

# Contributing #

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

# License #

[GNU General Public License, version 2](COPYING)