Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update JFR and monitoring docs #33107

Merged
merged 2 commits into from
May 15, 2023
Merged

Update JFR and monitoring docs #33107

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c3d44db
update JFR and monitoring docs
roberttoyonaga May 3, 2023
f2a8788
add mandrel to table
roberttoyonaga May 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion core/deployment/src/main/java/io/quarkus/deployment/pkg/NativeConfig.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,15 @@ default String getEffectiveBuilderImage() {
boolean enableVmInspection();

/**
* Enable monitoring options that allow the VM to be inspected at run time.
* Enable monitoring various monitoring options. The value should be comma separated.
* <ul>
* <li><code>jfr</code> for JDK flight recorder support</li>
* <li><code>jvmstat</code> for JVMStat support</li>
* <li><code>heapdump</code> for heampdump support</li>
* <li><code>jmxclient</code> for JMX client support (experimental)</li>
* <li><code>jmxserver</code> for JMX server support (experimental)</li>
* <li><code>all</code> for all monitoring features</li>
* </ul>
*/
Optional<List<MonitoringOption>> monitoring();

Expand Down Expand Up @@ -454,6 +462,8 @@ enum MonitoringOption {
HEAPDUMP,
JVMSTAT,
JFR,
JMXSERVER,
JMXCLIENT,
ALL
}
}
40 changes: 40 additions & 0 deletions docs/src/main/asciidoc/building-native-image.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -886,6 +886,46 @@ gdb -ex 'directory ./target' ./target/getting-started-1.0.0-SNAPSHOT-runner

For a more detailed guide about debugging native images please refer to the xref:native-reference.adoc[Native Reference Guide].

== Using Monitoring Options

Monitoring options such as JDK flight recorder, jvmstat, heap dumps, and remote JMX (experimental in Mandrel 23)
can be added to the native executable build. Simply supply a comma separated list of the monitoring options you wish to
include at build time.
[source,bash]
----
-Dquarkus.native.monitoring=<comma separated list of options>
----

|===
|Monitoring Option |Description |Availability As Of

|jfr
|Include JDK Flight Recorder support
|GraalVM CE 21.3 Mandrel 21.3

|jvmstat
|Adds jvmstat support
|GraalVM 22.3 Mandrel 22.3

|heapdump
|Adds support for generating heap dumps
|GraalVM 22.3 Mandrel 22.3

|jmxclient
|Adds support for connections to JMX servers.
|GraalVM for JDK 17/20 Mandrel 23.0
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: I am still not sure whether we will go with "Mandrel 23.0" or "Mandrel for JDK 17/20" as well.

cc @jerboaa @Karm

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We probably won't know for a bit, so we can leave it as it is and create an issue to revisit it once the June release comes in?


|jmxserver
|Adds support for accepting connections from JMX clients.
|GraalVM for JDK 17/20 Mandrel 23.0

|all
|Adds all monitoring options.
|GraalVM 22.3 Mandrel 22.3
|===

Please see the Quarkus Native Reference Guide for more detailed information on these monitoring options.

[[configuration-reference]]
== Configuring the Native Executable

Expand Down
43 changes: 35 additions & 8 deletions docs/src/main/asciidoc/native-reference.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2133,23 +2133,50 @@ $ ./mvnw package -DskipTests -Dnative \
https://docs.oracle.com/javacomponents/jmc-5-4/jfr-runtime-guide/about.htm#JFRUH170[Java Flight Recorder (JFR)] and
https://www.oracle.com/java/technologies/jdk-mission-control.html[JDK Mission Control (JMC)]
can be used to profile native binaries since GraalVM CE 21.2.0.
However, JFR in GraalVM is currently significantly limited in capabilities compared to HotSpot.
The custom event API is fully supported, but many VM level features are unavailable.
They will be added in future releases. Current limitations are:

* Minimal VM level events
However, JFR in GraalVM is currently limited in capabilities compared to HotSpot.
The custom event API is fully supported, but some VM level features are unavailable.
More events and JFR features will continue to be added in later releases.
The following table outlines Native Image JFR support and limitations by version.

[cols="2,5a,5a"]
|===
|GraalVM Version |Supports |Limitations

|GraalVM CE 21.3 and Mandrel 21.3
|* Minimal VM Level events
* Custom events API
* Start recordings upon executabe run or JFR Recording API
|
* No old object sampling
* No stacktrace tracing
* No Streaming API for JDK 17
* No event streaming

|GraalVM CE 22.3 and Mandrel 22.3
|* Everything from GraalVM CE 21.3
* Additional monitor and thread events
|* No old object sampling
* No stacktrace tracing
* No event streaming

|GraalVM CE for JDK 17/20 and Mandrel 23.0
|* Everything from GraalVM CE 22.3
* Additional monitor, thread, container, and allocation events
* Stacktraces
* Sampling based method profiling
* Event streaming
|* No old object sampling

|===


To use JFR add the application property: `-Dquarkus.native.enable-vm-inspection=true`.
To add JFR support to your Quarkus executable, add the application property: `-Dquarkus.native.monitoring=jfr`.
E.g.

[source,bash,subs=attributes+]
----
./mvnw package -DskipTests -Dnative -Dquarkus.native.container-build=true \
-Dquarkus.native.builder-image=quay.io/quarkus/ubi-quarkus-mandrel-builder-image:{mandrel-flavor} \
-Dquarkus.native.enable-vm-inspection=true
-Dquarkus.native.monitoring=jfr
----

Once the image is compiled, enable and start JFR via runtime flags: `-XX:+FlightRecorder` and `-XX:StartFlightRecording`. For example:
Expand Down