Top4J is a lightweight, low overhead, production-ready performance analysis tool for the Java Runtime Environment. As the name suggests, it works a bit like the UNIX/Linux top command but at the JVM-level exposing key performance metrics from a Java runtime perspective.
Top4J has two modes of operation: Remote Attach command-line interface (CLI) and Java Agent.
The Top4J Remote Attach function is executed via the command line and attaches to a remote JVM process via the JDK tools VirtualMachine API.
The Top4J Java Agent is invoked via the standard java -javaagent command line argument and runs as a background thread inside the target JVM.
See Getting Started section for more details.
Top4J is an open sourced component of the Open Answers Panther suite of monitoring applications.
The Top4J CLI jar must be run using a Java JDK install not a JRE.
Supported JDKs:
Oracle JDK 7, 8, 11
OpenJDK 7, 8, 11
There are no prerequisites for running the Top4J Java Agent (aside from downloading and installing the Top4J Java Agent jar file).
- Download and install the Top4J CLI jar within an appropriate location on the local file system.
- Run Top4J CLI jar as follows....
java -jar top4j-cli-1.1.0.jarNOTE: The Top4J CLI jar must be run as the target JVM process owner.
The Top4J CLI will auto-detect running, attachable JVMs and present a list of JVM processes to choose from....
java -jar top4j-cli-1.1.0.jar
0) org.tanukisoftware.wrapper.WrapperSimpleApp org.sonar.application.App [PID=8800]
1) org.sonar.server.app.WebServer C:\Users\ryan\AppData\Local\Temp\sq-process6076250228712711580properties [PID=9840]
2) io.top4j.javaagent.test.MultiThreadedTest 1000 100 1000 [PID=28756]
3) org.sonar.search.SearchServer C:\Users\ryan\AppData\Local\Temp\sq-process647990075843669775properties [PID=10876]
4) top4j-cli-1.1.0.jar [PID=7884]
Please select a JVM number between 0 and 4:....simply select the JVM number you want to profile and Top4J will do the rest.
Here's a screenshot of Top4J in action....
Alternatively, you can specify the target JVM PID on the command line as follows....
java -jar top4j-cli-1.1.0.jar -p 12345See the Top4J Command Line Interface documentation for the full set of command line options supported or use the "-h" command line option, e.g. java -jar top4j-cli-1.1.0.jar -h.
Some additional CLI screenshots can be found here.
- Download and install the Top4J Java Agent jar within an appropriate location on the local file system.
- Add
-javaagentcommand line argument to JVM startup args, e.g.
java -javaagent:<path-to-top4j-jar>/top4j-javaagent-1.1.0.jar <java-class-name>The performance metrics gathered by the Top4J Java Agent are exposed via standard JMX MBean attributes. See the Top4J JMX Interface for more details.
The Top4J Java Agent can also be configured to log performance metrics to the local file system. See the Top4J Logging documentation for more details.
The Top4J Java Agent is configured via a standard Java properties file. See the Top4J Configuration documentation for more details.
Make sure JDK 8+ and Maven 3.x are installed on your machine, then....
git clone https://github.com/OpenAnswers/top4j.git
cd top4j
mvn clean packagePlease read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
For general queries, please email the project team at top4j@openanswers.co.uk. If you think you've found a bug or have an enhancement request, please check the Top4J issue management database for existing issues before submitting a new issue.
Top4J uses a standard SemVer based semantic versioning scheme. For the versions available, see the tags on this repository.
- Ryan Young - Project founder - Open Answers
See also the list of contributors who have participated in this project.
This project is licensed under the Apache License 2.0 - see the LICENSE.txt file for more details
This project makes use of some excellent open source libraries including: