From c3d44dba03ecc0cc264577f7487be0eba57a4308 Mon Sep 17 00:00:00 2001 From: Robert Toyonaga Date: Wed, 3 May 2023 11:01:18 -0400 Subject: [PATCH 1/2] update JFR and monitoring docs --- .../quarkus/deployment/pkg/NativeConfig.java | 12 +++++- .../main/asciidoc/building-native-image.adoc | 40 +++++++++++++++++ docs/src/main/asciidoc/native-reference.adoc | 43 +++++++++++++++---- 3 files changed, 86 insertions(+), 9 deletions(-) diff --git a/core/deployment/src/main/java/io/quarkus/deployment/pkg/NativeConfig.java b/core/deployment/src/main/java/io/quarkus/deployment/pkg/NativeConfig.java index c51f7915711eb..0f00332f17113 100644 --- a/core/deployment/src/main/java/io/quarkus/deployment/pkg/NativeConfig.java +++ b/core/deployment/src/main/java/io/quarkus/deployment/pkg/NativeConfig.java @@ -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. + * */ Optional> monitoring(); @@ -454,6 +462,8 @@ enum MonitoringOption { HEAPDUMP, JVMSTAT, JFR, + JMXSERVER, + JMXCLIENT, ALL } } diff --git a/docs/src/main/asciidoc/building-native-image.adoc b/docs/src/main/asciidoc/building-native-image.adoc index a0a652df7085e..8620002a85b7a 100644 --- a/docs/src/main/asciidoc/building-native-image.adoc +++ b/docs/src/main/asciidoc/building-native-image.adoc @@ -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= +---- + +|=== +|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 + +|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 diff --git a/docs/src/main/asciidoc/native-reference.adoc b/docs/src/main/asciidoc/native-reference.adoc index ab2cadd835fba..52d8cbd4c7ef1 100644 --- a/docs/src/main/asciidoc/native-reference.adoc +++ b/docs/src/main/asciidoc/native-reference.adoc @@ -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 +|* 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 +|* 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 +|* 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: From f2a8788a2436300c6a3921da56ec13c1b70f9332 Mon Sep 17 00:00:00 2001 From: Robert Toyonaga Date: Thu, 11 May 2023 12:34:15 -0400 Subject: [PATCH 2/2] add mandrel to table --- docs/src/main/asciidoc/native-reference.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/main/asciidoc/native-reference.adoc b/docs/src/main/asciidoc/native-reference.adoc index 52d8cbd4c7ef1..e1c406f6d05bd 100644 --- a/docs/src/main/asciidoc/native-reference.adoc +++ b/docs/src/main/asciidoc/native-reference.adoc @@ -2142,7 +2142,7 @@ The following table outlines Native Image JFR support and limitations by version |=== |GraalVM Version |Supports |Limitations -|GraalVM CE 21.3 +|GraalVM CE 21.3 and Mandrel 21.3 |* Minimal VM Level events * Custom events API * Start recordings upon executabe run or JFR Recording API @@ -2151,14 +2151,14 @@ The following table outlines Native Image JFR support and limitations by version * No stacktrace tracing * No event streaming -|GraalVM CE 22.3 +|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 +|GraalVM CE for JDK 17/20 and Mandrel 23.0 |* Everything from GraalVM CE 22.3 * Additional monitor, thread, container, and allocation events * Stacktraces