Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Top4J Logo


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


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.1.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.1.0.jar

0) org.tanukisoftware.wrapper.WrapperSimpleApp org.sonar.application.App [PID=8800]
1) C:\Users\ryan\AppData\Local\Temp\sq-process6076250228712711580properties [PID=9840]
2) io.top4j.javaagent.test.MultiThreadedTest 1000 100 1000 [PID=28756]
3) 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....

Top4J Top Threads Screenshot

Alternatively, you can specify the target JVM PID on the command line as follows....

java -jar top4j-cli-1.1.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.1.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.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.

Build Top4J (via Maven)

Make sure JDK 8+ and Maven 3.x are installed on your machine, then....

git clone
cd top4j
mvn clean package


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


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:


Top4J is a lightweight, low overhead, production-ready performance analysis tool for the Java runtime environment







No packages published

Contributors 4