This project is collecting info on JFR events from JFR files and the OpenJDK source code, producing an extended metadata file which can be used by the JFR Event Explorer.
The extended metadata includes
- all events defined in the metadata.xml file and the JDK source code
- additional descriptions: please contribute yourself
- versions of the JDK in which every event, field, ... is present
- examples for events and their fields for the renaissance benchmark with different GCs
- AI generated descriptions for events and their fields
The event collection is presented at SapMachine, created by jfrevents-site-generator.
Add new descriptions for events, types or fields to the additional.xml file.
These descriptions should explain what the described entity represents and
how it can be interpreted and used during profiling.
I pledge to try to bring added descriptions into the OpenJDK (but only JDK head seems to be feasiable, so contributing it here still makes sense).
- The collector JAR: here.
- The collection JAR (with all extended metadata xmls at your fingertips): here.
- The metadata itself: look no further than the releases page of this repository
Useful when creating your own JFR Event Explorer like tool. The related JAR is called jfreventcollection.jar
in the releases.
// load and print the metadata for JDK 17
println(me.bechberger.collector.xml.Loader.load(17))The default processor run by the JAR processes a JFR file and prints all available information.
# small sample (3710 events, 47 event types)
java -jar jfreventcollector.jar samples/profile.jfrprofile.jfr is a recording of an execution of the renaissance benchmark suite
(https://github.com/renaissance-benchmarks/renaissance).
This adds the events found in the passed JDK source folder.
java -cp jfreventcollector.jar me.bechberger.collector.EventAdderKt <path to metadata.xml> \
<path to OpenJDK source> <path to result xml file> <url of main folder> <permanent url of main folder>This adds examples from the passed JFR file to the passed metadata file.
java -cp jfreventcollector.jar me.bechberger.collector.ExampleAdderKt <path to metadata.xml> <label of file> \
<description of file> <JFR file> ... <path to resulting metadata.xml>This adds jdks attributes to fields and events based on the passed metadata files.
java -cp jfreventcollector.jar me.bechberger.collector.SinceAdderKt <smallest version> \
<metadata file> <metadata output file> ...This adds additional descriptions to events and fields based on the passed metadata files.
This adds additional descriptions to events and fields based on the passed metadata files.
java -cp jfreventcollector.jar me.bechberger.collector.AdditionalDescriptionAdderKt <path to metadata.xml> \
<path to xml file with additional descriptions> <path to resulting metadata.xml>This adds AI generated descriptions to events based on the metadata and JDK source code.
java -cp jfreventcollector.jar me.bechberger.collector.AdditionalDescriptionAdderKt <path to metadata.xml> \
<path to OpenJDK source> <path to result xml file> It requires an .openai.key file in the current directory that has to contain your OpenAI key and server url:
key=<your key>
server=https://api.openai.comSee this blog post for more information.
This adds source code that is possibly related to an event to the metadata. This includes the path, the line numbers with potential matches and the surrounding code.
java -cp jfreventcollector.jar me.bechberger.collector.SourceCodeContextAdderKt <path to metadata.xml> \
<path to OpenJDK source> <path to result xml file> <optional: context lines per match, default 25> \
<optional: max lines of context, default 500>This script helps to build the extended metadata file for every JDK version (starting with JDK11). It should be run under the most recent released JDK version to obtain proper JFR examples.
The current snapshot version is 0.6-SNAPSHOT:
<dependency>
<groupId>me.bechberger</groupId>
<artifactId>jfreventcollector</artifactId>
<version>0.6-SNAPSHOT</version>
</dependency><dependency>
<groupId>me.bechberger</groupId>
<artifactId>jfreventcollection</artifactId>
<version>0.6-SNAPSHOT</version>
</dependency>You might have to add the https://s01.oss.sonatype.org/content/repositories/releases/ repo:
To use snapshots, you have to add the snapshot repository:
<repositories>
<repository>
<id>snapshots</id>
<url>https://s01.oss.sonatype.org/content/repositories/snapshots/</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>Use the bin/releaser.sh script:
Usage:
python3 releaser.py <command> ... <command> [--force]
Commands:
versions print all available JDK versions
tags print the current tag for all JDK versions
download_urls print the latest source code download URLs for every JDK version
download download the latest source code for every JDK version
build_parser build the parser JAR
create_jfr create the JFR file for every available GC
build_versions build the extended metadata file for every available JDK version
build build the JAR with the extended metadata files
deploy_mvn deploy the JARs to Maven
deploy_gh deploy the JARs and XML files to GitHub
deploy the two above
deploy_release deploy the JARs and XML files to GitHub and Maven as releases
all download, build_parser, ..., deploy_gh
clear clear some folders
Options:
--force forces all forceable commands to execute
Commands "all", "create_jfr", "build_versions" can be forced
by appending "=force" to them, e.g. "all=force".
Environment variables:
LOG set to "true" to print more informationRun bin/releaser.py download build_parser build_versions build deploy.
Only run bin/releaser.py create_jfr if you have a new JDK version installed.
Builds might take longer on newer maven versions due to blocking of http resources (and I don't know which). Maven 3.6.3 seems to work fine.
Apache 2.0, Copyright 2023 SAP SE or an SAP affiliate company, Johannes Bechberger and contributors