Attaching to a JVM image that does not include java.instrument

[Rafael Winterhalter]

Hi Alan,

I just retested with the most recent Java 9 snapshot and this is what I get:

rafael at rafc:~/jdk9-test/greetingsapp$ ./bin/java
-javaagent:/home/rafael/.m2/repository/sample-agent/sample-agent/1.0-SNAPSHOT/sample-agent-1.0-SNAPSHOT.jar
-m com.greetings/com.greetings.Main
Error occurred during initialization of VM
Could not find agent library instrument on the library path, with error:
libinstrument.so: cannot open shared object file: No such file or directory
rafael at rafc:~/jdk9-test/greetingsapp$ ./bin/java --add-modules
java.instrument
-javaagent:/home/rafael/.m2/repository/sample-agent/sample-agent/1.0-SNAPSHOT/sample-agent-1.0-SNAPSHOT.jar
-m com.greetings/com.greetings.Main
Error occurred during initialization of VM
Could not find agent library instrument on the library path, with error:
libinstrument.so: cannot open shared object file: No such file or directory
rafael at rafc:~/jdk9-test/greetingsapp$ ./bin/java --add-modules
java.instrument -m com.greetings/com.greetings.MainError occurred during
initialization of boot layer
java.lang.module.FindException: Module java.instrument not found

Do I understand you correctly that you expect the last outcome also as a
result for the first command?

I argue that this outcome would still be rather suprising for most Java
users. Many monitoring tools use Java agents to hook into Java processes
and those tools have become omnipresent in most production environments.
Also, it is very unlikely that a main application module would require the
java.instrument module as it is only useful to Java agents. As a result,
Java agents and the tooling that relies on them would stop working for the
majority of jlink modules. Furthermore, the agent attachment also fails if
a Javaagent does not require the Instrumentation interface what makes this
problem even less intuitive. (The reason being the lack of libinstrument.)

Consider the follwoing runtime environment which I have seen at customers
dozens of times:

rafael at rafc:~/jdk9-test/greetingsapp$ export
_JAVA_OPTIONS=-javaagent:/home/rafael/.m2/repository/sample-agent/sample-agent/1.0-SNAPSHOT/sample-agent-1.0-SNAPSHOT.jar
rafael at rafc:~/jdk9-test/greetingsapp$ ./bin/java -m
com.greetings/com.greetings.Main
Picked up _JAVA_OPTIONS:
-javaagent:/home/rafael/.m2/repository/sample-agent/sample-agent/1.0-SNAPSHOT/sample-agent-1.0-SNAPSHOT.jar
Error occurred during initialization of VM
Could not find agent library instrument on the library path, with error:
libinstrument.so: cannot open shared object file: No such file or directory

On the above machine, a jlink image is incapable of starting despite the
_JAVA_OPTIONS only specifying standard features that are guaranteed by the
JVM independently of a specific VM vendor.

To resolve this, I think that the jlink tools should always resolve the
java.instrument module. Right now, it is most likely creating a JVM image
that is not compatible to the majority of existing tooling, including the
tooling provided by Oracle. Other than the experimental options and the
management extension, the Java agent mechanism is part of the officially
documented options which is supported by any JVM implementation (e.g. it is
listed by java --help). That this feature is practically unavailable unless
the java.instrument module is resolved (which might just happen
accidentally when a certain module requires java.instrument transitively)
could backfire when discovered late, for example when it is impossible to
debug a production process when it yields an error after a few weeks that
would require introspection of the process which is usually done using a
Java agent. In the worst case, an application could be distributed by a
vendor who is not aware of tooling being used to monitor Java processes
where building the image is not governed by those relying on
java.instrument.

I further argue that java.instrument should be part of java.base what might
be the easiest solution to this problem. The instrumentation API is a core
feature to any JVM and any Java agent should be able to start on any JVM
distribution. If a Java agent requires APIs that is not provided by a JVM
image due to missing modules beyond java.instrument, the Javaagent can in
such cases detect such lacking functionality at runtime and choose to fail
with a proper error message or to offer some reduced functionality. The
java.instrument types however are part of the startup signature which is
why they should always be included.

I really hope you consider this. Java agents often seem like a feature used
by only a few people but I have rarely seen a production environment where
they are not used in some form. In the end, this would also affect Oracle
customers and Oracle products.

Best regards, Rafael

2017-05-18 17:19 GMT+02:00 Alan Bateman <Alan.Bateman at oracle.com>:

> On 18/05/2017 15:20, Rafael Winterhalter wrote:
>
> Hei,
>>
>> I found that it is impossible to dynamically attach to a JVM that does not
>> include the java.instrument module when built with jlink. This is a result
>> of the instrumentation API and its infrastructure missing from the image.
>>
>> rafael at rafc:~/jdk9-test/greetingsapp$ ./bin/java
>> -javaagent:/home/rafael/.m2/repository/sample-agent/sample-
>> agent/1.0-SNAPSHOT/sample-agent-1.0-SNAPSHOT.jar
>> -m com.greetings/com.greetings.Main
>> Error occurred during initialization of VM
>>
>> Could not find agent library instrument on the library path, with error:
>> libinstrument.so: cannot open shared object file: No such file or
>> directory
>>
> Ugh, when -javaagent is specified then it is supposed to work as if
> `--add-modules java.instrument` is also on the command line. This ensures
> that the java.instrument module is resolved. The intention was also to get
> a useful error if the run-time image doesn't contain java.instrument.
>
> Another example is `-Dcom.sun.management.*` which should work as if
> `--add-modules jdk.management.agent` is specified on the command line. Also
> `-XX:+UnlockExperimentalVMOptions -XX:+EnableJVMCI` which is supposed to
> add `--add-modules jdk.internal.vm.ci`. I just checked both of these and
> the error is helpful as I expected.
>
> As regards the attach mechanism then it will work when it is compiled in
> and enabled in the target VM. When I say "compiled in" then I mean the
> support is in libjvm. When using jlink when you can select the minimal VM
> to get a much smaller VM that doesn't have the serviceability features.
> That won't be typical of course so assume it is libjvm then you should be
> able to attach and troubleshooting tools such as `jcmd` will work. If you
> attempt to load a java agent then the target VM will attempt to resolve and
> load the java.instrument module and so will fail if the run-time image
> doesn't have the module.
>
> You are right that java.instrument is small but it's always been a goal to
> be able to create run-time images that only contain java.base.
>
> I didn't understand your comment about an "unused warnings" in the IDE. Do
> you mean `requires java.instrument` rather than specifying java.instrument
> to the `jlink --add-modules` option?
>
> -Alan
>