Skip to content
Top4J is a lightweight, low overhead, production-ready performance analysis tool for the Java runtime environment
Java Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.idea Add additional check to ConsoleController updateScreen() method to ma… Sep 19, 2019
docs Set theme jekyll-theme-slate Sep 23, 2019
images Add additional top4j screenshots to README. Sep 11, 2019
top4j-cli [maven-release-plugin] prepare for next development iteration Sep 20, 2019
top4j-javaagent Add JavaDoc comments to Top4J JMX MBean interfaces. Sep 22, 2019
.editorconfig Reformat code. Add .editorconfig file. Sep 20, 2019
.gitignore Update .gitignore. Remove some IntelliJ generated files from source c… Sep 18, 2019
.travis.yml Add .travis.yml file. Oct 10, 2019
CONTRIBUTING.md Update README.md, CONTRIBUTING.md and JMX_INTERFACE.md. Sep 20, 2019
LICENSE.txt Add LICENSE.txt Aug 16, 2019
README.md Update README.md Sep 23, 2019
pom.xml
top4j-parent.iml Add blocked threads screen CLI functionality. Jun 18, 2019

README.md

Top4J Logo

Description

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.

Getting Started

Prerequisites

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).

Run Top4J via CLI Remote Attach

  1. Download and install the Top4J CLI jar within an appropriate location on the local file system.
  2. 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....

Top4J Top Threads Screenshot

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

  1. Download and install the Top4J Java Agent jar within an appropriate location on the local file system.
  2. Add -javaagent command 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.

The Top4J Java Agent is configured via a standard Java properties file. See the Top4J Configuration 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

Contributing

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 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.

Versioning

Top4J uses a standard SemVer based semantic versioning scheme. For the versions available, see the tags on this repository.

Authors

See also the list of contributors who have participated in this project.

License

This project is licensed under the Apache License 2.0 - see the LICENSE.txt file for more details

Acknowledgments

This project makes use of some excellent open source libraries including:

You can’t perform that action at this time.