Native image agent integration with JVM mode tests #36822
Assignees
Labels
Comments
|
This work has uncovered a small bug in the resource pattern json production: #36823 |
|
nice work @galderz ! |
|
@vsevel Yeah, it's about running jvm mode tests with the agent, then taking the config that the agent has generated and feeding it into the native image process. There's some filtering we will be doing to avoid Quarkus and/or non-application related test configuration going in. See the linked draft for further discussions. |
|
I have tried, but could not get the I can see I am using quarkus maven plugin and also but I am not seeing any |
|
@vsevel If you want to try this out, as well as building the branch locally, you need to either create a new Quarkus maven project with the following command (you can adjust name, extensions...etc): mvn io.quarkus:quarkus-maven-plugin:999-SNAPSHOT:create \
-DprojectGroupId=org.acme \
-DprojectArtifactId=my-project \
-Dextensions='resteasy-reactive' \
-DplatformVersion=999-SNAPSHOTOr if you have an existing Quarkus project, once you modified the Quarkus version, add the following profile to the pom.xml: |
|
it worked. thanks. I am actually surprised with all that I see. I believe this app is working fine in native. so I do not understand why there are fasterxml classes, or caffeine, or arjuna, ... the output: |
Right, we're still fine tuning things so I would need to see what the causes for these registrations are to be able to explain them better. If this is a project you can share with me I can look into it. Otherwise if you can generate trace output and configuration origins (as explained in the description), I can try to see if I can filter things further. A note about resource configuration. Filtering before the native image agent runs doesn't work that well (see oracle/graal#8417), so I'm doing post-filtering here. I can enhance that filter with some of the things I see in your output, but it would help to make sure I'm doing this right with a trace output and configuration origins. Then, about serialization, I've tried to remove everything except any JDK types because I can't fully guarantee they are not in use unless they're filtered by the agent itself with the filters we provide to it. |
|
I executed no |
|
I made the relevant files available here |
|
@vsevel I have updated the PR. Could you please have a go again and see what things look like now, and see if the issues you spotted are gone? |
|
I won't be able to work on this topic before 2 weeks (but I won't forget :-) |
|
can't start the app during the IT test. I execute: it launches: the quarkus.log says: note: in the target dir, I do have the quarkus-access-filter.json and quarkus-caller-filter.json there must be an option I am missing on the docker command. for instance am I supposed to have a |
|
Assuming the |
|
I tried on a linux box @galderz a directory was created with name I did not see much in the logs: is it supposed to push something in the logs? |
No, the logs won't show anything any more. As noted in my comment in #36826 (comment), a CI job can do this after the JVM integration tests have run and display them nicely (e.g. with I'm still looking at the windows issue. |
|
Also, the reflection configuration that you see looks right. There are some additional registrations that originate in the JDK but we can't really filter those without affecting other use cases down the line. |
ok. so all the exported and filtered files are in
fair enough
this would be nice, because we might position it as a dev tool, rather than a CI tool. i.e. documenting how to run these commands from the (windows) developer machine. |
|
I was able to run the docker command on a windows prompt with: instead of (generated by verify command): the 2 changes are:
with those changes, the app starts successfully: funny enough, I can't get this to work from git bash. |
|
finally got it to work on git bash (and that's ugly): had to use |
Actually, Thanks for helping working out the docker command for windows. I did suspect the |
I do not have the final folder: |
|
Ah yes, you need to make sure you add the |
|
that works better. |
|
by the way, I talked to a couple of people doing the eap migrations about this feature. and they definitely see the value. this is going to be very well received by the teams I think. |
|
@vsevel I pushed a fix to the branch to change the jar path and that was enough to make the test I had added pass. The volume path structure is fine so need to fiddle with that. Let us know when you're happy and we can get this integrated. I will create a follow up task to enable extensions to register pakages that can be filtered (e.g. caffeine, kafka...etc). |
|
I just tested and everything works perfectly indeed @galderz, both in windows and git bash shell. looks good! |
This was referenced Apr 30, 2024
|
@galderz is this considered complete? If not could you please provide an update on what needs to be done? (Ideally by updating the issue description) Thanks |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Motivation
Quarkus users that want to integrate new libraries/components into native image process (e.g. smbj), or want to use JDK APIs that require extensive native image configuration to work (e.g. graphical user interfaces), face a considerable challenge coming up with the native image configuration to make their use cases work.
These users can tweak their applications to run in JVM mode with the native image agent in order to auto-generate native image configuration that will help them get a head start getting applications to work as native executables. However, this is both cumbersome to do and the configuration produced contains a lot of superfluous configuration that the Quarkus integration takes care of.
The aim of the Quarkus native image agent integration is to make the native image agent integration as seamless as possible and to make sure the configuration produced removes, as much as possible, configuration that Quarkus already takes care of.
Description
In this initial native image agent integration, the focus is on the Quarkus users being able to run JVM mode integration tests on Quarkus Maven applications transparently with the native image agent.
To do this, a container runtime is necessary because JVM mode integration tests will run using the JVM within the default Mandrel builder container image. This image contains the native image agent libraries required to produce native image configuration, hence avoiding the need for a local Mandrel or GraalVM installation.
NOTE: It is strongly recommended that subsequent native image builds that use the generated configuration are in-container, using the same Mandrel builder container image. Generating native image configuration with the same Mandrel image as the one that builds the native image is the best guarantee to avoid invalid configuration being produced.
With a container runtime running, invoke Maven's
verifygoal with-DskipITs=false -Dquarkus.test.integration-test-profile=test-with-native-agentto run the JVM mode integration tests and generate the native image configuration. For example:To achieve this output, the native image integration agent follows this process:
First, it generates native image agent configuration filters. These filters exclude commonly used packages in Quarkus applications because native image configurations related to those are not necessary to run the native executable. These filters are expressed in JSON format and are stored inside
target/quarkus-access-filter.jsonandtarget/quarkus-caller-filter.jsonfiles.Secondly, the
javaprocess that runs the integration tests is enhanced with the following JVM parameters. When the integration tests complete, thetarget/native-image-agent-base-configcontains the native image configuration files generated by the agent:Thirdly, the filters generated in the first step cover most of the native image configuration use cases that Quarkus already takes care of, but resource configuration filtering is not fully working as expected (see oracle/graal#8417 for details). So, in this step the resource configuration is trimmed to remove unnecessary resource configuration. All the configuration is then transferred into the
target/native-image-agent-final-configfolder.Informative By Default
By default the generated native image configuration files are not used by subsequent native image building processes. This precaution is taken to avoid situations where seemingly unrelated actions have unintended consequences on the native executable produced, e.g. disabling randomly failing tests.
By informing the developer of the generated native image configuration, they can copy/paste the output into files (or copy the files from the folder) to be stored under source control and evolve as needed. Ideally these files should be stored under the
src/main/resources/META-INF/native-image/<group-id>/<artifact-id>folder, in which case the native image process will automatically pick them up.It is possible to instruct Quarkus to optionally apply the generated native image configuration files into subsequent native image processes, by setting the
-Dquarkus.native.agent-configuration-applyproperty. This can be useful to verify that the native integration tests work as expected, assuming that the JVM unit tests have generated the correct native image configuration.If managing native image agent configuration files manually, it is highly recommended to regenerate them each time a Mandrel version update occurs, because the configuration necessary to make the application work might have varied due to internal Mandrel changes.
Debugging Native Image Agent Integration
If the generated native image agent configuration does not satisfy the needs of Quarkus users, they can obtain more information using any of the following techniques.
Debugging Filters
If native image agent is generating a configuration that it’s not working as expected, you should check that the configuration files include the expected information. For example, if some method happens to be accessed via reflection at runtime and you get an error, you want to verify that the configuration file contains a reflection entry for that method.
If the entry is missing, it could be that some call path is being filtered that maybe shouldn’t have been. To verify that, inspect the contents of
target/quarkus-caller-filter.jsonandtarget/quarkus-access-filter.jsonfiles, and confirm that the class and/or package making the call or being accessed is not being filtered out.If the missing entry is related to some resource, you should inspect the Quarkus build debug output and verify which resource patterns are being discarded, e.g.
Trace Output
A native image agent configuration trace output JSON file can be generated using the following additional system properties:
When trace output is configured, no native image configuration is generated, and instead a
target/native-image-agent-trace-file.jsonfile is generated that contains trace information. For example:$ tail ./target/native-image-agent-trace-file.json {"tracer":"reflect", "function":"newInstance", "class":"java.lang.reflect.Array", "caller_class":"java.util.IdentityHashMap$KeySet", "result":"true", "args":["[Lio.netty.util.concurrent.FastThreadLocal;"]}, ...Unfortunately the trace output does not take into account the applied configuration filters, so the output contains all configuration decisions made by the agent. This is unlikely to change in the near future (see oracle/graal#7635).
Configuration With Origins (Experimental)
Alternative to the trace output, it is possible to configure the native image agent with an experimental flag that shows the origins of the configuration entries. You can enable that with the following additional system property:
$ ./mvnw clean test -Dnative-with-agent -Dquarkus.test.native.agent.additional.args=experimental-configuration-with-originsThe origins of the configuration entries can be found in text files inside the
target/native-image-agent-base-config folder. For example:$ tail ./target/native-image-agent-base-config/reflect-origins.txt └── org.acme.GreetingResource$quarkusrestinvoker$greeting_709ef95cd764548a2bbac83843a7f4cdd8077016#invoke(java.lang.Object,java.lang.Object[]) └── org.acme.GreetingResource#greeting(java.lang.String) └── org.acme.GreetingService_ClientProxy#greeting(java.lang.String) └── org.acme.GreetingService#greeting(java.lang.String) ├── java.lang.Class#forName(java.lang.String) - [ { "name":"org.acme.Alice" }, { "name":"org.acme.Bob" } ] ├── java.lang.Class#getDeclaredConstructor(java.lang.Class[]) - [ { "name":"org.acme.Alice", "methods":[{"name":"<init>","parameterTypes":[] }] } ] ├── java.lang.reflect.Constructor#newInstance(java.lang.Object[]) - [ { "name":"org.acme.Alice", "methods":[{"name":"<init>","parameterTypes":[] }] } ] ├── java.lang.reflect.Method#invoke(java.lang.Object,java.lang.Object[]) - [ { "name":"org.acme.Alice", "methods":[{"name":"sayMyName","parameterTypes":[] }] } ] └── java.lang.Class#getMethod(java.lang.String,java.lang.Class[]) - [ { "name":"org.acme.Alice", "methods":[{"name":"sayMyName","parameterTypes":[] }] } ]Debugging With GDB
The native image agent itself is a native executable produced with GraalVM that uses JVMTI to intercept the calls that require native image configuration. As a last resort, it is possible to debug the native image agent with GDB, see here for instructions on how to do that.
Testing
A sample Maven project has been created that contains a pom.xml with the new profile under
integration-tests/maven/target/test-classes/projects/native-agent-integration. The project includes an endpoint that will only succeed if reflection configuration has been generated and applied to the native executable. This is one use case where-Dquarkus.native.agent-configuration-applyis used to automate the process of applying the configuration and get confidence that the native image agent integration is working as expected.Future Work
The text was updated successfully, but these errors were encountered: