Microsoft GCToolKit
GCToolkit is a set of libraries for analyzing HotSpot Java garbage collection (GC) log files. The toolkit parses GC log files into discrete events and provides an API for aggregating data from those events. This allows the user to create arbitrary and complex analyses of the state of managed memory in the Java Virtual Machine (JVM) represented by the garbage collection log.
For more detail you can read our Launch Blog Post.
Introduction
Managed memory in the Java Virtual Machine (JVM) is comprised of 3 main pieces:
- Memory buffers known as Java heap
- Allocators which perform the work of getting data into Java heap
- Garbage Collection (GC).
While GC is responsible for recovering memory in Java heap that is no longer in use, the term is often used as a euphemism for memory management. The phrasing of Tuning GC or tuning the collector are often used with the understanding that it refers to tuning the JVM’s memory management subsystem. The best source of telemetry data for tuning GC comes from GC Logs and GCToolKit has been helpful in making this task easier by providing parsers, models and an API to build analytics with. You can run the Maven project HeapOccupancyAfterCollectionSummary sample as an example of this.
Prerequisite for Building GCTooKit
The gctoolkit build relies on test data which is archived in GitHub Packages. This requires you to authenticate to GitHub packages with a personal access token (PAT) to build and test.
If your organization uses Single Sign-On (SSO), also follow the directions under Authorizing a personal access token for use with SAML single sign-on.
You must also add github as a server in your ~/.m2/settings.xml file. Replace USERNAME with your GitHub user name and TOKEN with your PAT.
<server>
<id>github</id>
<username>USERNAME</username>
<password>TOKEN</password>
</server>
Getting Started
Maven Coordinates
The GCToolKit artifacts are in GitHub packages. To use the GCToolKit artifacts as dependencies in your project, github must be added as a repository in your POM file.
<repository>
<id>github</id>
<name>GCToolKit packages</name>
<url>https://maven.pkg.github.com/microsoft/*</url>
</repository>
<dependency>
<groupId>com.microsoft.gctoolkit</groupId>
<artifactId>api</artifactId>
<version>2.0.1</version>
</dependency>
<dependency>
<groupId>com.microsoft.gctoolkit</groupId>
<artifactId>parser</artifactId>
<version>2.0.1</version>
</dependency>
<dependency>
<groupId>com.microsoft.gctoolkit</groupId>
<artifactId>vertx</artifactId>
<version>2.0.1</version>
</dependency>
Example
See sample/README
Build and Test
The build is vanilla Maven.
mvn clean- remove build artifactsmvn compile- compile the source codemvn test- run unit tests (this project uses TestNG)mvn package- build the .jar files
Additional build properties
skipUnpack- boolean. Defaults tofalse. This tells the build to skip unpacking the gctoolkit-testdata logs. If the test data has already be extracted to the gclogs directory, setting this property totruecan save a minute or so of build time.
Contributing
See CONTRIBUTING for full details.
License
Microsoft GCToolKit is licensed under the MIT license.
![[ZGC] Add GC ID to the ZGCCycle](https://avatars.githubusercontent.com/u/111525238?v=4)
271 Jan 8, 2023
14 Dec 7, 2022
9 Oct 16, 2022
1.2k Jan 2, 2023
642 Dec 14, 2022
847 Nov 26, 2022
1.8k Dec 29, 2022
637 Jan 5, 2023
3.2k Dec 18, 2022
24 May 10, 2022
142 Jan 1, 2023
1.2k Dec 21, 2022
965 Dec 30, 2022
94 Oct 15, 2022
127 Nov 23, 2022
2 Mar 19, 2022
3 Dec 4, 2021
4 Oct 2, 2022
13.2k Jan 5, 2023