Address review comments

Author: steverao

examples/distro/README.md

@@ -37,12 +37,12 @@ The following description follows one specific use-case:
 As an example, let us take some database client instrumentation that creates a span for database call
 and extracts data from db connection to provide attributes for that span.
 
-### I want to customize instrumentation without modifying core code
+### I want to customize instrumentation without modifying the instrumentation
 
-The `InstrumenterCustomizerProvider` extension point allows you to customize instrumentation behavior without modifying core code:
+The `InstrumenterCustomizerProvider` extension point allows you to customize instrumentation behavior without modifying the instrumentation:
 
 - Add custom attributes and metrics to existing instrumentations
-- Implement context customizers for request correlation
+- Customize context
 - Transform span names to match your naming conventions
 - Apply customizations conditionally based on instrumentation type and span kind
 

examples/distro/build.gradle

@@ -45,7 +45,6 @@ subprojects {
   }
 
   repositories {
-    mavenLocal()
     mavenCentral()
     maven {
       name = "sonatype"

examples/distro/custom/src/main/java/com/example/javaagent/DemoInstrumenterCustomizerProvider.java

@@ -126,7 +126,6 @@ public Context onStart(Context context, Object request, Attributes startAttribut
       String requestId = "req-" + requestIdCounter.getAndIncrement();
 
       // Add custom context data that can be accessed throughout the request lifecycle
-      // This follows the pattern used in real implementations like UndertowSingletons
       context = context.with(REQUEST_ID_KEY, requestId);
       return context;
     }

examples/extension/README.md

@@ -67,12 +67,12 @@ Extensions are designed to override or customize the instrumentation provided by
 
 Consider an instrumented database client that creates a span per database call and extracts data from the database connection to provide span attributes. The following are sample use cases for that scenario that can be solved by using extensions.
 
-### "I want to customize instrumentation without modifying core code"
+### "I want to customize instrumentation without modifying the instrumentation"
 
-The `InstrumenterCustomizerProvider` extension point allows you to customize instrumentation behavior without modifying core code:
+The `InstrumenterCustomizerProvider` extension point allows you to customize instrumentation behavior without modifying the instrumentation:
 
 - Add custom attributes and metrics to existing instrumentations
-- Implement context customizers for request correlation
+- Customize context
 - Transform span names to match your naming conventions
 - Apply customizations conditionally based on instrumentation type and span kind
 

examples/extension/build.gradle

@@ -36,7 +36,6 @@ ext {
 }
 
 repositories {
-  mavenLocal()
   mavenCentral()
   maven {
     name = "sonatype"

examples/extension/src/main/java/com/example/javaagent/DemoInstrumenterCustomizerProvider.java

@@ -128,7 +128,6 @@ public Context onStart(Context context, Object request, Attributes startAttribut
       String requestId = "req-" + requestIdCounter.getAndIncrement();
 
       // Add custom context data that can be accessed throughout the request lifecycle
-      // This follows the pattern used in real implementations like UndertowSingletons
       context = context.with(REQUEST_ID_KEY, requestId);
       return context;
     }

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/instrumenter/InstrumenterCustomizer.java

@@ -12,36 +12,36 @@
 import java.util.function.Function;
 
 /**
- * A service provider interface (SPI) for providing customizations for instrumentation, including
- * operation metrics, attributes extraction, and context customization.
+ * Provides customizations for instrumentation, including operation metrics, attributes extraction,
+ * and context customization.
  *
- * <p>This allows external modules or plugins to contribute custom logic for specific instrumented
- * libraries, without modifying core instrumentation code. This class is internal and is hence not
- * for public use. Its APIs are unstable and can change at any time.
+ * <p>This class is passed to {@link
+ * InstrumenterCustomizerProvider#customize(InstrumenterCustomizer)} to allow external modules or
+ * plugins to contribute custom logic for specific instrumented libraries, without modifying core
+ * instrumentation code. This class is internal and is hence not for public use. Its APIs are
+ * unstable and can change at any time.
  */
 public interface InstrumenterCustomizer {
 
   /**
-   * Returns the name of the instrumentation that this customizer applies to. This allows for
-   * efficient mapping of customizers to specific instrumentations rather than using predicates for
-   * matching.
+   * Returns the name of the instrumentation that this customizer applies to.
    *
    * @return the name of the instrumentation this customizer targets
    */
   String getInstrumentationName();
 
   /**
-   * Adds a single AttributesExtractor to the instrumenter. This extractor will be used to extract
-   * attributes from requests and responses during span creation and enrichment.
+   * Adds a single {@link AttributesExtractor} to the instrumenter. This extractor will be used to
+   * extract attributes from requests and responses during the request lifecycle.
    *
    * @param extractor the attributes extractor to add
    * @return this InstrumenterCustomizer for method chaining
    */
   InstrumenterCustomizer addAttributesExtractor(AttributesExtractor<?, ?> extractor);
 
   /**
-   * Adds multiple AttributesExtractors to the instrumenter. These extractors will be used to
-   * extract attributes from requests and responses during span creation and enrichment.
+   * Adds multiple {@link AttributesExtractor}s to the instrumenter. These extractors will be used
+   * to extract attributes from requests and responses during the request lifecycle.
    *
    * @param extractors the collection of attributes extractors to add
    * @return this InstrumenterCustomizer for method chaining
@@ -50,26 +50,26 @@ InstrumenterCustomizer addAttributesExtractors(
       Iterable<? extends AttributesExtractor<?, ?>> extractors);
 
   /**
-   * Adds an OperationMetrics implementation to the instrumenter. This will be used to create
-   * metrics capturing the request processing metrics for the instrumented operations.
+   * Adds an {@link OperationMetrics} implementation to the instrumenter. This will be used to
+   * create metrics for the instrumented operations.
    *
    * @param operationMetrics the metrics factory to add
    * @return this InstrumenterCustomizer for method chaining
    */
   InstrumenterCustomizer addOperationMetrics(OperationMetrics operationMetrics);
 
   /**
-   * Sets a ContextCustomizer for the instrumenter. The customizer will modify the context during
-   * the Instrumenter.start() operation, allowing custom context propagation or enrichment.
+   * Adds a {@link ContextCustomizer} that will customize the context during {@link
+   * Instrumenter#start(Context, Object)}.
    *
-   * @param customizer the context customizer to set
+   * @param customizer the context customizer to add
    * @return this InstrumenterCustomizer for method chaining
    */
   InstrumenterCustomizer addContextCustomizer(ContextCustomizer<?> customizer);
 
   /**
-   * Sets a transformer function that will modify the SpanNameExtractor. This allows customizing how
-   * span names are generated for the instrumented operations.
+   * Sets a transformer function that will modify the {@link SpanNameExtractor}. This allows
+   * customizing how span names are generated for the instrumented operations.
    *
    * @param spanNameExtractorTransformer function that transforms the original span name extractor
    * @return this InstrumenterCustomizer for method chaining