How do I pass arguments to a Java instrumentation agent?

Question

How do I pass arguments to a java.lang.instrument instrumentation agent? The documentation simply states:

-javaagent:jarpath[=options]

What options can I select?

Solution

To pass arguments to a Java agent, append them after the equals sign:

java -javaagent:/path/to/agent.jar=argumentstring -cp jar-under-test.jar Foo.Main

The arguments are treated as a single string and passed to your premain method. You are responsible for any further processing of the arguments, e.g. splitting on commas or separating key=value pairs.

public static void premain(String agentArgument,Instrumentation instrumentation){
  // args passed in 'agentArgument'
}

Note: if you don't pass any arguments to your agent (i.e. omitting the equals sign), the agentArgument argument will be null, rather than an empty string.

Comments

[philburns]

how can I pass a non-null instrumentation argument?

[Walter]

instrumentation is provided by the JVM, that is not something that is user-controlled.