[GR-55707] Java Agents Support in Native Image

[alina-yur]

This ticket summarizes the current status and next steps for Java agent support in Native Image.

Current status

At build time, bytecode transformation can be done by passing a Java agent to Native Image with -J-javaagent:agent.jar. Things to note:

• The agent is running and transforming all classes at build time.
• The premain of the agent is only executed at build time.
• The agent is currently marked as link-at-build-time so all of the classes need to be present in the agent jar.
• The agent should not touch the classes that are used by native-image itself, as this might interfere with the build or result in unpredictable behavior at run time. Instrumenting JDK classes should work to a large degree but there are a few pitfalls:
  • Too complex instrumentation (e.g., introducing Java heap allocation or synchronization) may break the image build or execution at run-time (Native Image assumes for some JDK methods that they only contain trivial code).
  • Native Image substitutes some JDK code with a custom implementation. Instrumenting such JDK code is not possible as the substitution takes precedence (i.e., it will look as if the JDK code was not instrumented).

Goals

• Simplify and improve agent support at build time:
  • Support agents at image generation time
  • A potential implementation
• Explore removing the limitation of linking at build time
• Explore executing premain at runtime
• Explore limiting the scope of Native Image classes that the agent can transform

Non-goals

• Allowing agents to transform classes at runtime

[cemo]

@alina-yur, Is there any coordinated effort from Oracle to resolve this issue? I see there is an open PR but I think it is not addressed by current maintainers of the project. At the end of that effort that PR might be not accepted as well. Is it not a good idea to review that PR and making a better way?

It sounds probably strange but after that PR resolved adoption of the Graal will increase dramatically. Many companies are using agents for APM tools and every single release we are reading release notes to see that this issue resolved or not.

[adinn]

It sounds probably strange but after that PR resolved adoption of the Graal will increase dramatically. Many companies are using agents for APM tools and every single release we are reading release notes to see that this issue resolved or not.

I think you need to reset your expectations of any 'solution'. The qualifications Olga mentioned are not just something to be 'resolved' by a clever redesign. They are intrinsic to what can be achieved here -- because they rule out things that many agents rely on being able to do (there are more issues -- for example, agents that depend on creating service threads under their premain method). In consequence there will be a lot of cases where agents that are used at runtime on the JVM cannot be used at build time to modify behaviour of a generated native image.

As an example, my agent, Byteman, as currently designed, cannot possibly be used to instrument a native image at build time. I am not going to say it is impossible to implement an equivalent for GraalVM Native but I currently don't know how to do it (and, yes, I designed and implemented all the core functionality of Byteman). My expectation is that my (many thousands of) users who rely on using Byteman for testing, tracing and debugging are never going to be able to use it for those purposes with a GraalVM Native app.

Luckily, my users can still benefit from using Byteman on the JVM during development and maintenance of a GraalVM Native app and the tight equivalence in behaviour of a GraalVM Native vs JVM deployment means they can still test, trace and debug most problems that way. However, I do have a significant number of users who rely on Byteman to troubleshoot problems in live deployments and they are out of luck if they choose to deploy using GraalVM Native.

That said, I fully accept that there are agents where build time vs runtime instrumentation makes no difference. So that means a resolution of this issue would be very welcome. Just remember that any such solution will not be universal.

[chenzhiguo]

I am very concerned about when this feature will be implemented?

[vjovanov]

From the GraalVM Workshop: we should prevent the agent from transforming the JDK classes in the host VM as they can affect how the image builder works.

To allow transformation of JDK classes we can take all classes that are not substituted and apply the transformation ourselves, similarly to Native Image annotations. For inspiration we can use the snippet from NetBeans as proposed by @JaroslavTulach.

[JaroslavTulach]

To allow transformation of JDK classes we can take all classes that are not substituted and apply the transformation ourselves, similarly to Native Image annotations. For inspiration we can use the snippet from NetBeans as proposed by @JaroslavTulach.

There may be another use-case for this automatic(?) Agent-Class invocation that would solve an open issue with WASM backend for GraalVM and its integration with HTML/Java API.

When the use of javaagent option was discussed I realised (to my surprise) there already is such an agent for the HTML/Java API. The net.java.html.boot.jar can be used as -javaagent as it has Agent-Class in its manifest.

It transforms the (usually native) methods annotated by @JavaScriptBody annotation into real methods with body that invoke Fn.Presenter's defineFn method. E.g. it is not something that would affect JDK classes, but invoking such Agent-Class declared agent automatically on bytecode by SVM before emitting the native code might help to solve the WASM backend for GraalVM and HTML/Java API issue.

Just FYI. CCing @patrick96