https://github.com/andreastu/jctrace
Java Concurrency Tracer
https://github.com/andreastu/jctrace
asm concurrent-programming deadlock instrumentation java trace
Last synced: about 1 month ago
JSON representation
Java Concurrency Tracer
- Host: GitHub
- URL: https://github.com/andreastu/jctrace
- Owner: AndreasTu
- License: apache-2.0
- Created: 2017-09-02T10:59:01.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2023-06-16T11:26:02.000Z (over 2 years ago)
- Last Synced: 2025-03-26T23:33:16.618Z (7 months ago)
- Topics: asm, concurrent-programming, deadlock, instrumentation, java, trace
- Language: Java
- Size: 1.37 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
- License: LICENSE
Awesome Lists containing this project
README
# JConcurrency Tracer (jctrace)
The JConcurrency Tracer allows you to find deadlocks in your Java application.
The JConcurrency Tracer instruments a Java application to find **potential** deadlocks in the system.
Jctrace will create a database of all taken and release locks in the application.
In a second step jctrace will calculate if any two locks have any threads, where the lock order is inverse, which will flag a potential deadlock.
**Note:** Not every flagged potential deadlock, will be a real deadlock in your system.
E.g. if you can guarantee that the found lock orders can not happen at the same time, the potential deadlock can not happen.
But it would be no good concurrency design to rely on these fragile terms.
## Analysis details
Jctrace will instrument and measure the following items:
* `synchronized` keyword
* For any `Object` or `Class` instance
* `synchronized` methods
* `java.util.concurrent.locks.ReentrantLock`
* `java.util.concurrent.locks.ReentrantReadWriteLock`
* `java.util.concurrent.locks.StampedLock`
The jctrace is currently only tested with Java 8 and Java 11.
Jctrace could also create stack traces of found potential deadlocks to ease the fix of the underlying problem.
## How to build jctrace?
To build the project just run:
```
gradlew shadowJar
```
The built jar file it then located in `subprojects/jctrace-core/build/libs/jctrace-core-1.0.0-SNAPSHOT-all.jar
## Create a measurement
First you have to create a measurement of your running application.
Start your application with the following additional Java-VM arguments:
```
-javaagent:jctrace-core-1.0.0-SNAPSHOT-all.jar
-Xbootclasspath/a:jctrace-core-1.0.0-SNAPSHOT-all.jar
-Dde.turban.DeadLockTracer.blacklist=org.eclipse;com.google
-Dde.turban.DeadLockTracer.stacktracingClasses=;
```
You could blacklist whole packages including all sub packages with `-Dde.turban.DeadLockTracer.blacklist=`.
Packages are separated with an `;`.
#### Stacktrace
You could enable the collection of stack traces for certain classes with `-Dde.turban.DeadLockTracer.stacktracingClasses`
Class names are separated with an `;`.
##### Full sample
Full Path sample:
```
-javaagent:/Path/To/Jar/File/jctrace-core-1.0.0-SNAPSHOT-all.jar
-Xbootclasspath/a:/Path/To/Jar/File/jctrace-core-1.0.0-SNAPSHOT-all.jar
-Dde.turban.DeadLockTracer.blacklist=org.eclipse;com.google;org.apache;java;sun;org.osgi;com.sun;org.codehaus.groovy;groovy
-Dde.turban.DeadLockTracer.stacktracingClasses=pkg.to.class.ClassNameA;pkg.to.other.class.ClassB
-Djava.util.logging.config.file=/Your/path/to/logging.properties
```
## Open UI to evaluate the Database
You could open the UI with:
```
gradlew run -PdbFile=Deadlock.db
```
Note: In the current version the UI will the show anything, if there is no potential deadlock.
## Create a report
Or you could create an XML report from the Database, if you call:
```
gradlew runReportXml -PdbFile=Deadlock.db -PreportFile=DeadlockReport.xml
```
## Further work to do (wish list)
* Improve the usability of the UI
* Make the Load/Close buttons work correctly
* Display text, if not potential deadlock was found
* Improve the usability of measurement creation with a wrapper which calls the java application
* Add instrumentation for volatile field reads and writes to detect data races
* Add instrumentation for Atomic* classes reads and writes to detect data races
## Contributors
* Creator:
* Andreas Turban (GitHub: AndreasTu)