# HG changeset patch # User Yasumasa Suenaga # Date 1570240271 -32400 # Node ID 839f92246d301488e1e29bd303add7773bae153c # Parent c544d27e27c20b8913c49c91e335e273cbdb0429 Bug 3753: Update README.md Reviewed-by: ykubota https://github.com/HeapStats/heapstats/pull/146 diff -r c544d27e27c2 -r 839f92246d30 ChangeLog --- a/ChangeLog Sat Oct 05 10:41:03 2019 +0900 +++ b/ChangeLog Sat Oct 05 10:51:11 2019 +0900 @@ -1,6 +1,7 @@ 2019-10-05 Yasumasa Suenaga * Bug 3754: Could not bundle heapstats-cli launcher + * Bug 3753: Update README.md 2019-09-27 Yasumasa Suenaga diff -r c544d27e27c2 -r 839f92246d30 INSTALL --- a/INSTALL Sat Oct 05 10:41:03 2019 +0900 +++ b/INSTALL Sat Oct 05 10:51:11 2019 +0900 @@ -5,7 +5,7 @@ 1. Pre-Requirements Agent: - - Java SE 6 or later + - JDK 7 or later - Maven2 or later - Ant 1.8 or later - pcre-devel 6 or later @@ -16,32 +16,18 @@ libtbb2 and libtbb-dev in official Debian repository. Analyzer: - - Java SE 8 or later - - JavaFX 8 or later + - JDK 13 or later + - JavaFX 13 or later - Maven2 or later 2. How to build - (1) run configure with path to JDK 8 - - $ ./configure --with-jdk=/path/to/JDK8 - - *HINT* HeapStats Analyzer requires JavaFX 8. - OpenJDK does not provide JavaFX. Open source JavaFX is OpenJFX. - If you have not installed OpenJFX, You have to pass OracleJDK8. + Run `configure` and `make` as following: - (2) run make + $ ./configure --with-jdk=/path/to/JDK13 $ make - *HINT* If your machine does not have JavaFX (OpenJFX or OracleJDK), - you can avoid to build HeapStats Analyzer as below: - - $ make agent <- build HeapStats agent - $ make mbean <- build HeapStats MBean - $ mvn -am -pl analyzer/cli package <- build HeapStats CLI - - configure script provides several useful options. If you want to know them, please run "./configure --help" . diff -r c544d27e27c2 -r 839f92246d30 README --- a/README Sat Oct 05 10:41:03 2019 +0900 +++ b/README Sat Oct 05 10:51:11 2019 +0900 @@ -1,49 +1,86 @@ HeapStats =================== -HeapStats is Java troubleshooting tool. -This tool is composed of three programs: +HeapStats is Java troubleshooting tool. +This tool suites of three applications. * Agent - * HeapStats JVMTI agent for gathering JavaVM runtime information continuously. + * HeapStats JVMTI agent for gathering JavaVM runtime information continuously. * Analyzer - * HeapStats JavaFX GUI analyzer for analysis by various graphs. + * HeapStats JavaFX GUI analyzer for analysis by various graphs. * CLI - * HeapStats commandline analyzer. + * 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 # 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 - * and more. More detailed is [here](http://icedtea.classpath.org/wiki/HeapStats/information_to_be_collected). +* 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 + +## How to use ## You can attach HeapStats agent by any way of the following: -* -agentlib:heapstats[=conf] - * If libheapstats.so is located at LD_LIBRARY_PATH, you can pass -agentlib option to java. -* -agentpath:/path/to/heapstats[=conf] - * Pass libheapstats.so with -agentpath option to java. -* heapstats-attacher - * If you want to attach HeapStats to existed process, you can use this script. +* `-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 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 ## -If you want to set specified configuration, you can pass it to -agentlib/-agentpath after "=config file" . +* GNU make +* Apache Ant +* GCC +* JDK 7 or later +* Intel TBB +* NetSNMP +* GNU Binutils - -## Analyzer ## +See also: [HeapStats Builder](https://github.com/HeapStats/heapstats-builder) -HeapStats analyzer is GUI application for analyzing HeapStats SnapShot. -You can run it on any GUI environment which has JavaFX runtime. +# Analyzer # + +Analyzer is GUI application for analyzing data which are collected from Agent. +Also it supports JDP autodiscovery and Error Report Transmission. -HeapStats analyzer supports JDP autodiscovery and Error Report Transmission. +## Requirements ## + +Linux x64 or Windows x64 + +## How to use ## + +Run `/bin/heapstats-analyzer` (Linux) or `\bin\heapstats-analyzer.bat` (Windows) ### JDP ### -The automatic discovery function of JDP (Java Discovery Protocol) can be -enabled by the following JVM options. +The automatic discovery on JDP (Java Discovery Protocol) can be enabled by the following JVM options. ``` -Dcom.sun.management.jmxremote.port= @@ -52,38 +89,65 @@ -Dcom.sun.management.jmxremote.autodiscovery=true ``` -The JDP function sends a packet at regular intervals: 5 seconds by default. -If analyzer can NOT receive a JDP packet from a monitoring JVM instance, -the instance's name displayed on the screen will become orange. +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 ### -OracleJDK can provide a real-time detection of JVM crash, but OpenJDK does -NOT support it. In addition, OracleJDK needs to be run with the following options. +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=
: ``` -## CLI ## +**NOTE: Error Report Transmission has been removed since JDK 12** + +## Build requirements ## + +* Apache Maven +* JDK 13 or later + +# CLI # -If you want to analyze HeapStats SnapShot on CUI environment, you can use HeapStats 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 - $ heapstats-cli +## How to use ## + +Run `/bin/heapstats-cli` (Linux) or `\bin\heapstats-cli.bat` (Windows) + +If you want to see options, please run `heapstats-cli` with `-help`. -If you want to see details, please run heapstats-cli with -help . +## Build requirements ## + +* Apache Maven +* JDK 13 or later -## Documents and Binaries ## +# Documents and Binaries # + +More detailes and released binaries are available on icedtea community: http://icedtea.classpath.org/wiki/HeapStats + +# Build all # -More detailed documents and released binaries are hosted at icedtea community: http://icedtea.classpath.org/wiki/HeapStats +``` +$ configure --with-jdk=/path/to/jdk13 +$ make +``` -## Contributing ## +# 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](https://github.com/HeapStats/heapstats/blob/master/CONTRIBUTING.md) for details. +See [CONTRIBUTING.md](CONTRIBUTING.md) for details. -## License ## +# License # - [GNU General Public License, version 2](https://github.com/HeapStats/heapstats/blob/master/COPYING) +[GNU General Public License, version 2](COPYING) diff -r c544d27e27c2 -r 839f92246d30 agent/attacher/README.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/agent/attacher/README.md Sat Oct 05 10:51:11 2019 +0900 @@ -0,0 +1,21 @@ +HeapStats Attacher +=================== + +HeapStats Attacher can attach JVMTI agent such as HeapStats Agent to existed process. + +# Requirements # + +* Oracle JDK / OpenJDK 7 or later + +# How to use # + +``` +$ heapstats-attacher /path/to/libheapstats.so [heapstats.conf] +``` + +# Build requirements # + +* Apache Ant +* JDK 7 or later + +You can build HeapStats Attacher with top of `Makefile` with `agent` target. diff -r c544d27e27c2 -r 839f92246d30 mbean/README.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mbean/README.md Sat Oct 05 10:51:11 2019 +0900 @@ -0,0 +1,37 @@ +HeapStats MBean +=================== + +HeapStats MBean adds the feature to access HeapStats Agent which is attached to its process via JMX. +It is composed to two modules: + +* `heapstats-mbean.jar` + * Providing MBean and related configuration file + * Including `jboss-service.xml` for adding this ability to JBoss and/or WildFly +* `libheapstats-mbean.so` + * Native part of HeapStats MBean + * Required by `heapstats-mbean.jar` + +# Requirements # + +* HeapStats Agent +* Linux x64 / x86_64 / AArch32 +* Oracle JDK / OpenJDK + +# How to use # + +1. Deploy `heapstats-mbean.jar` and `libheapstats-mbean.so` to your application +2. Enable JMX on your application +3. Access to `heapstats:type=HeapStats` + +You can access to HeapStats MBean via JVMLive on HeapStats Analyzer or HeapStats CLI. + +Implementation examples are available on [test of Agent](../agent/test/mbean). + +# Build requirements # + +* GNU make +* Apache Maven +* GCC +* JDK 7 or later + +You can build HeapStats MBean with top of `Makefile` with `mbean` target.