Add a ConfigProvider callback for runtime instrumentation option changes

api/incubator/src/main/java/io/opentelemetry/api/incubator/config/ConfigProvider.java

@@ -65,6 +65,20 @@ default DeclarativeConfigProperties getGeneralInstrumentationConfig() {
     return getInstrumentationConfig().get("general");
   }
 
+  /**
+   * Registers an {@link InstrumentationConfigChangeListener} to receive updates when
+   * instrumentation configuration changes.
+   *
+   * <p>The default implementation performs no registration and returns a no-op handle.
+   *
+   * @param listener the listener to notify when instrumentation configuration changes
+   * @return an {@link AutoCloseable} handle that can be closed to unregister the listener
+   */
+  default AutoCloseable addInstrumentationConfigChangeListener(
+      InstrumentationConfigChangeListener listener) {
+    return () -> {};
+  }
+
   /** Returns a no-op {@link ConfigProvider}. */
   static ConfigProvider noop() {
     return DeclarativeConfigProperties::empty;

api/incubator/src/main/java/io/opentelemetry/api/incubator/config/InstrumentationConfigChangeListener.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.config;
+
+import javax.annotation.Nullable;
+
+/** Listener notified when instrumentation configuration changes. */
+@FunctionalInterface
+public interface InstrumentationConfigChangeListener {
+
+  /**
+   * Called when the effective config for one top-level instrumentation node changes (for example
+   * {@code methods}, {@code kafka}, or {@code grpc}).
+   *
+   * <p>Both config arguments are scoped to {@code instrumentationName}.
+   *
+   * <p>{@code newConfig} is never null. If the node is unset or cleared, {@code newConfig} is
+   * {@link DeclarativeConfigProperties#empty()}.
+   *
+   * @param instrumentationName the top-level instrumentation name that changed
+   * @param previousConfig the previous effective configuration, or {@code null} if unavailable
+   * @param newConfig the updated effective configuration for {@code instrumentationName}
+   */
+  void onChange(
+      String instrumentationName,
+      @Nullable DeclarativeConfigProperties previousConfig,
+      DeclarativeConfigProperties newConfig);
+}

api/incubator/src/test/java/io/opentelemetry/api/incubator/ConfigProviderTest.java

@@ -6,6 +6,7 @@
 package io.opentelemetry.api.incubator;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
 
 import io.opentelemetry.api.incubator.config.ConfigProvider;
 import org.junit.jupiter.api.Test;
@@ -24,5 +25,8 @@ void instrumentationConfigFallback() {
     assertThat(configProvider.getInstrumentationConfig()).isNotNull();
     assertThat(configProvider.getInstrumentationConfig("servlet")).isNotNull();
     assertThat(configProvider.getGeneralInstrumentationConfig()).isNotNull();
+    AutoCloseable listenerRegistration =
+        configProvider.addInstrumentationConfigChangeListener((name, previous, current) -> {});
+    assertThatCode(listenerRegistration::close).doesNotThrowAnyException();
   }
 }