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 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.
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).
Run Top4J via CLI Remote Attach
- 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.0.0.jar
NOTE: 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.0.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.0.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.0.0.jar -p 12345
See 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.0.0.jar -h.
Some additional CLI screenshots can be found here.
Run Top4J as a Java Agent
- Download and install the Top4J Java Agent jar within an appropriate location on the local file system.
-javaagentcommand line argument to JVM startup args, e.g.
java -javaagent:<path-to-top4j-jar>/top4j-javaagent-1.0.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.
Build Top4J (via Maven)
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 package
Please 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 email@example.com. 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.
- 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: