Minimum Example or Documentation For Writing JVMTI Agents in Java

[sixbitproxywax]

Hello,

I am wanting to learn and write some tutorials about GraalVM, JVMTI and other related things, but I am having trouble making headway and can't seem to find the documentation I need.

I am currently trying to write a JVMTI agent in Java. I have found the jvmti-agent-base dependency and I am able to build my subclass of the JvmtiAgentBase class to a shared library and launch Java with it for a simple application.

However, I keep getting the error message "No agent has been registered but an instance was requested*

From the Javadocs, it is not clear to me what I need to do.

Does any sort of tutorial or sample code with a minimum functional example exist? If not, I'd be glad to write it, but I need some guidance!

Here is my attempt at a minimum example:

  @Override
  protected JNIHandleSet constructJavaHandles(JNIEnvironment env) {
    return new JNIHandleSet(env) {
    };
  }

  @Override
  protected int onLoadCallback(JNIJavaVM vm, JvmtiEnv jvmti, JvmtiEventCallbacks callbacks, String options) {
    System.out.println("on load");
    return 0;
  }

  @Override
  protected int onUnloadCallback(JNIJavaVM vm) {
    System.out.println("on unload");
    return 0;
  }

  @Override
  protected void onVMStartCallback(JvmtiEnv jvmti, JNIEnvironment jni) {
    System.out.println("on vm start");
  }

  @Override
  protected void onVMInitCallback(JvmtiEnv jvmti, JNIEnvironment jni, JNIObjectHandle thread) {
    System.out.println("on vm init");
  }

  @Override
  protected void onVMDeathCallback(JvmtiEnv jvmti, JNIEnvironment jni) {
    System.out.println("on vm death");
  }

  @Override
  protected int getRequiredJvmtiVersion() {
    return JvmtiInterface.JVMTI_VERSION_1_2;
  }

which I attempt to use with:

java -agentpath:/root/simple-graal-jvmti-agent/target/simple-graal-jvmti-agent.so [...]

Any tips to get me headed in the right direction would be appreciated!

[sixbitproxywax]

Ok, I took another look at the native agent in graal and managed to get the RegistrationFeature and build args squared away.

I still would appreciate it if someone would explain why the RegistrationFeature is used instead of a simple static initializer or something to initialize the singleton. I'm sure there's a good reason, but I have not yet found and explanation for why this is necessary.

[anderruiz]

Hi @sixbitproxywax were you able to define any other method in your agent?, I'm able to receive the normal callbacks but I'm trying to hook onClassFileLoadHook. My callback is being called in fact (once I did all the proper configuration) but my problem is how to map the real method:

void JNICALL ClassFileLoadHook(jvmtiEnv* jvmti, JNIEnv* jni, jclass class_being_redefined, jobject loader, const char* name, jobject protection_domain, jint data_len, const unsigned char* data, jint* new_data_len, unsigned char** new_data) {

To the java one, and how I should access the values. I saw that in VMInit callback jthread is being mapped to JNIObjectHandle, but I don't know what to do them, because if you invoke JNIObjectHandles.getObject I get and exception

[sixbitproxywax]

I, unfortunately, did not have time to dedicate to this in general.

[anderruiz]

I was able to figure out how to make it work, for documentation purposes I leave it here:

EntryPointLiteral:

CEntryPointLiteral<CFunctionPointer> onClassFileLoadHookLiteral = CEntryPointLiteral.create(JvmtiAgent.class,
			"onClassFileLoadHook", JvmtiEnv.class, JNIEnvironment.class, JNIObjectHandle.class, JNIObjectHandle.class,
			CCharPointer.class, Object.class,
			int.class,
			CCharPointer.class, CIntPointer.class, CCharPointerPointer.class);

Method signature (may not be 100% accurate as I don't use all the parameters):

@CEntryPoint()
@CEntryPointOptions(prologue = AgentIsolate.Prologue.class)
public static void onClassFileLoadHook(final JvmtiEnv jvmti, final JNIEnvironment jni, 
	final JNIObjectHandle clazz, final JNIObjectHandle loader, final CCharPointer name, 
        final Object protectionDomain, final int dataLen, final CCharPointer data,
	final CIntPointer newDataLength, final CCharPointerPointer newData)

Event activation:

@Override
protected int onLoadCallback(final JNIJavaVM vm, final JvmtiEnv jvmti, final JvmtiEventCallbacks callbacks, final String options) {
	callbacks.setClassFileLoadHook(onClassFileLoadHookLiteral.getFunctionPointer());
	check(jvmti.getFunctions().SetEventNotificationMode().invoke(jvmti, JVMTI_ENABLE, 
                 JvmtiEvent.JVMTI_EVENT_CLASS_FILE_LOAD_HOOK, nullHandle()));
	return 0;
}

[sixbitproxywax]

Awesome. I don't remember if I still have the workspace I was using, but would it be possible for you to do a very simple write-up on how to set up the project, config, etc. to get this going. I'd like to dig back into this and it would also probably be helpful to others (I remember it was a bit of a pain to track down everything I needed to do).

[anderruiz]

Sure, this is more or less my complete configuration:

dependencies in maven, you need to include jvmti-agent-base classes in your final jar, I use maven-shade-plugin for that

		<dependency>
			<groupId>org.graalvm.nativeimage</groupId>
			<artifactId>jvmti-agent-base</artifactId>
			<version>21.2.0</version>
		</dependency>
		<dependency>
			<groupId>org.graalvm.nativeimage</groupId>
			<artifactId>svm</artifactId>
			<version>21.2.0</version>
			<scope>provided</scope>
		</dependency>

Automatic feature that will connect your agent with the build process:

import com.oracle.svm.core.annotate.AutomaticFeature;

@AutomaticFeature
public class JvmtiFeature implements org.graalvm.nativeimage.hosted.Feature {

	@Override
	public void afterRegistration(final AfterRegistrationAccess access) {
		JvmtiAgent.register(); // Your agent
	}

}

Minimum Agent Class

public class JvmtiAgent extends JvmtiAgentBase<JNIHandleSet> {

	public static void register() {
		registerAgent(new JvmtiAgent());
	}

	@Override
	protected JNIHandleSet constructJavaHandles(final JNIEnvironment env) {
		return new JNIHandleSet(env) {
		};
	}

	@Override
	protected int getRequiredJvmtiVersion() {
		return JvmtiInterface.JVMTI_VERSION_1_2;
	}

	@Override
	protected int onLoadCallback(final JNIJavaVM vm, final JvmtiEnv jvmti, final JvmtiEventCallbacks callbacks, final String options) {
		return 0;
	}

	@Override
	protected int onUnloadCallback(final JNIJavaVM vm) {
		return 0;
	}

	@Override
	protected void onVMDeathCallback(final JvmtiEnv jvmti, final JNIEnvironment jni) {
	}

	@Override
	protected void onVMInitCallback(final JvmtiEnv jvmti, final JNIEnvironment jni, final JNIObjectHandle thread) {
	}

	@Override
	protected void onVMStartCallback(final JvmtiEnv jvmti, final JNIEnvironment jni) {
	}

}

If you want to add a new event callback then, follow the steps on my previous comment