Making "methods" instrumentation dynamically updateable

[jackshirazi]

Is your feature request related to a problem? Please describe.

An API that let's the methods instrumentation have methods instrumented at runtime, and also have any existing method instrumentation disabled at runtime
Conceptually, I think 3 API methods, like

• listCurrentInstrumentedMethods
• instrumentMethod(class, method, maybe spankind)
• disableInstrumentedMethod(class, method)

Describe the solution you'd like

Ideally it's just changes in the method instrumentation. But it would need to be accessible from an extension, which means that I think I need to add an interface to the javaagent-bootstrap module, and I'm not sure how acceptable that is. Or are there other ways to make the internal APIs available externally?

Describe alternatives you've considered

An alternative is to reimplement the full instrumentation as an extension and only have that dyamically updateable, leaving the existing one static and using the env var to determine which methods were instrumented so that the new one doesn't try to duplicate instrumentation on those. In some ways, this is the cleaner option, even though it's duplication of code

Additional context

part of open-telemetry/opentelemetry-java-contrib#2416

Tip

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}

[trask]

Instead of 3 API methods, can it be configuration driven, since I think we want a generic way to update instrumentation configuration for other use cases too?

[jackshirazi]

I think that implies polling something. I'd be fine with that. But what? The env var can't change, and I don't think the ConfigProperties are available or even guaranteed mutable. We could use the system property, anything can update that so it's a valid globally usable mutable config option, and polling should be low enough frequency that the synchronization overhead doesn't matter at all. Then it's just a matter of diffing the list on each poll, which is pretty clean. Good?

[trask]

I'd be interested in how this can work with the new ConfigProvider

it could imply polling getInstrumentationConfig()

or maybe adding a ConfigListener that instrumentations can register to listen for updates

[jackshirazi]

Hmm, I'm a bit lost. I think what you suggest means

1. create an extension which registers a dynamic config provider that is globally accessible from AgentInstrumentationConfig.get();
2. change methods instrumentation to poll that (lets ignore a callback option for the mo)
3. have the extension update the dynamic config provider

I don't think there is a way to do 1 ?

Actually, I think I'm wrong, it can be a custom one. Let me play around

[jackshirazi]

Okay, I think it would work - but if there are multiple ConfigProvider implementations, I think only one would get loaded and there's no way to guarantee it's this one? That seems problematic as this is an extension and there could be multiple extensions the user wants

[jackshirazi]

Gave this some thought. I realized that we can use a mutable config provider if available, and if not fallback to system property. So it would look like this

1. Add ConfigProvider.isMutable() default method returning false
2. Add interface MutableConfigProvider extends ConfigProvider with a void updateOption(String key, @Nullable Object value);
3. Add a OptionCallbackRegistry class which
   • allows anything to registerCallback(String key, Object currentValue, BiConsumer<String, Object> callback)
   • provides an updateOption(String key, Object value) which uses the MutableConfigProvider if present, otherwise uses System property
   • has a thread which periodically checks for changes and executes callbacks for any change associated with registered keys

Note that different instances of the OptionCallbackRegistry can be loaded by different classloaders and this all works fine globally, though at the cost of an extra thread for each classloader

[jackshirazi]

Actually I hit a blocker that I think prevents ConfigProvider as an option. The isDeclarative() method returns true if a ConfigProvider is defined. This means that if I include a custom ConfigProvider, everything will assume we're using declarative config at startup and expect that to be fully defined, but I don't have that config because I'm not actually using declarative config. And mapping all config into the custom ConfigProvider is pretty much impossible

[jackshirazi]

This isn't really progressing, so here's a concrete proposal that we can discuss

[jackshirazi]

Note that we discussed this at the 2025-12-04 Java SIG and the preference is to wait until the System Properties to ConfigProvider bridge is complete, and then implement using only a ConfigProvider callback rather than using System Properties as the intermediary