threadwatch

KO | EN

gitlite — search

#javascript #python #hacktoberfest #llm #linux #nodejs #windows #awesome #cli #awesome-list #vue #mcp #openai #open-source

(★ 8)

A JVMTI agent that creates high-resolution (1000 samples/second) snapshots of thread state transitions along with a Java program to view the results.

threadwatch Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

ThreadWatch
-----------

This project contains

- a JVMTI monitoring agent that can be hooked into a JVM to capture Java thread state transitions and write them to a file using a proprietary binary format
- a Swing application to plot a the thread states on a timeline

![screenshot](https://github.com/toby1984/threadwatch/blob/master/screenshot.png?raw=true)

Requirements for compiling the JVMTI agent
------------------------------------------

Beware: I only tested compilation on my 64-bit Ubuntu 12.04. You may need additional/different compiler flags and/or paths for your environment.

- GNU C / make
- libpthread
- glibc
- Some Linux header files
- JVMTI header files matching the JDK you want to use the agent with

Note that the JVMTI header files are part of the regular JDK and usually reside in ${JAVA_HOME}/include and ${JAVA_HOME}/include/linux

Requirements for compiling the GUI application
----------------------------------------------

- Apache Maven >= 2.2.1
- JDK 1.7+

Building the JVTI agent
-----------------------

To build, the agent:

````
Step 1: cd agent
Step 2: Adjust the Makefile to point to your JDK's C header files (${JAVA_HOME}/include and ${JAVA_HOME}/include/linux)
Step 3: make clean all
````

If all went well, you should find a shared library named agent.so inside the target folder.

Building the GUI application
----------------------------

Assuming you have a JDK and Maven 2.2.1+ installed, just run

````
mvn clean package
````

in the top-level folder. This should generate an executable JAR named threadwatcher.jar inside the target folder.

Running the JVMTI agent
-----------------------

The only way to run the agent is by passing it as a command-line option when starting the JVM, it's currently not possible to attach the agent to an already running JVM.

To start a JVM with the agent, use

````
java -agentpath:<path/to/agent.so>[=key=value[,key=value]] ....
````
Note that the agent will immediately start to capture thread state transitions and write them to a file.

The following options are understood by the agent:

<table>
<tr>
  <td>Name</td>
  <td>Value</td>
  <td>Description</td>  
</tr>
<tr>
  <td>verbose</td><td>ignored (but required!)</td><td>Enable verbose logging to std out</td>
</tr>
<tr>
  <td>file</td><td>Path to output file</td><td>File to write thread-state transitions to</td>
</tr>
<tr>
  <td>maxdelay</td><td>max. delay loop iterations</td><td>&lt;see below&gt;</td>
</tr>  
</table>

The 'maxdelay' options requires some explanation:

The agent tries to sample states of all running threads at least once every millisecond (= 1000 times per second). Since the actual wall-clock
time needed to do this depends on the number of threads currently running, background load etc. there's no point in using
a hard-coded sleep(X) inside this loop. Instead the agent continously measures the actual time needed for one iteration and the
uses a PID regulator to dynamically adjust the sampling speed to match 1000 samples/sec. 
I calibrated the regulator on a i5-2500K and also tested it on some other machines but it *MIGHT* be that your machine is way
more powerful than these and thus the default max. delay is still too low to not exceed the 1000 samples/sec.

A clear sign that your machine is "too" fast is (while running in verbose mode) that the number of samples keeps increasing way past the
1000 samples/sec. In this case, use the 'maxdelay' option and pass a value greater than the default (10000) to give the algorithm more leeway to slow-down the sampling loop.

Running the GUI application
---------------------------

The Maven build creates a self-executable JAR named 'threadwatcher.jar'.

To run the application, pass the output file of the agent as a command-line argument like so:

````
java -jar threadwatcher.jar <agent output file> 
````

The GUI application supports the following keyboard controls to navigate the data:

<table>
  <tr>
    <td>Key</td>
    <td>Description</td>
  </tr>
  <tr>
    <td>a</td>
    <td>Go back 1/4 display resolution</td>
  <tr>  
  <tr>
    <td>d</td>
    <td>Advance 1/4 display resolution</td>
  <tr>
  <tr>
    <td>w</td>
    <td>Zoom in</td>
  <tr>  
  <tr>
    <td>s</td>
    <td>Zoom out</td>
  <tr>   
</table>

- Left+click and drag inside the chart to select a time window to zoom into. 
- Right+click and drag to select a time range to get statistics for. You can move the start/end of this region by left-clicking and dragging.

threadwatch

threadwatch Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

threadwatch

threadwatch Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README