Base of AWS SDK v2.2 SPI Implementation (#1111)

Note: this is not the complete SPI implementation 

### Issue
The current ADOT Java SDK implementation relies on a combination of
OpenTelemetry SPI and Git patches to extend the OTel SDK functionality.
This approach presents several challenges:

- Reduced modularity and maintainability
- Increased risk of errors during OTel SDK version upgrades
- Manual intervention required for patch management
- Limited ecosystem compatibility with upstream OpenTelemetry
- Difficulty in extending functionality for users

This is the skeleton set up for the SPI, which aims to remove the
[patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch)
for aws-sdk v2.2 by using OTel's InstrumentationModule SPI extension.
This instrumentation is essentially complementing the upstream java
agent. It is completely separate from upstream and instruments after the
Otel agent.

### Description of Changes
This PR sets up the foundational structure for AWS SDK v2.2
Instrumentation, moving away from the current patching approach. It
doesn't modify current ADOT functionality or the upstream span. It just
registers the ADOT SPI implementation and sets up the interceptor hooks.

#### Core Components

1. **AdotAwsSdkInstrumentationModule**
   - Extends OpenTelemetry's `InstrumentationModule` SPI
   - Registers custom interceptors in specific order:
     1. Upstream AWS SDK execution interceptor
     2. ADOT custom interceptor
- Ensures proper instrumentation sequencing through careful resource
registration

2. **AdotTracingExecutionInterceptor**
   - Extends AWS SDK's `ExecutionInterceptor`
   - Hooks into key SDK lifecycle points:
- `beforeTransmission`: Captures final SDK request after upstream
modifications
- `modifyResponse`: Processes response before span closure in upstream
   - Will be used to enriches spans
   - Acts as central coordinator for all the awssdk_v2_2 components

3. **Resources Folder**
- Registers the AdotAwsSdkInstrumentationModule into OTel's SPI
extension classpath in META-INF/services
- Registers AdotTracingExecutionInterceptor into AWS SDK's interceptor
classpath in software.amazon.awssdk.global.handlers

### Key Design Decisions
1. **Instrumentation Ordering**
   - Deliberately structured to run after upstream OTel agent
   - Ensures all upstream modifications are captured
   - Maintains compatibility with existing instrumentation

2. **Lifecycle Hook Points**
   - `beforeTransmission`: Last point to access modified request
   - `modifyResponse`: Final opportunity to enrich span before closure
   - Carefully chosen to ensure complete attribute capture

### Testing
- Verified existing functionality remains unchanged and contract tests
pass (all contract tests pass after following the steps
[here](https://github.com/aws-observability/aws-otel-java-instrumentation/tree/main/appsignals-tests))
- Confirmed build success with new structure

### Benefits of using SPI
- Improved Maintainability: Clear separation between OTel core and
AWS-specific instrumentation
- Better Extensibility: Users can more easily extend or modify
AWS-specific behavior
- Reduced Risk: Eliminates manual patching during OTel upgrades
- Enhanced Compatibility: Better alignment with OpenTelemetry's
extension mechanisms
- Clearer Code Organization: More intuitive structure for future
contributions

By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license.

Author: anahatAWS

instrumentation/aws-sdk/README.md

@@ -0,0 +1,38 @@
+## ADOT AWS SDK Instrumentation
+
+### Overview
+The aws-sdk instrumentation is an SPI-based implementation that extends the upstream OpenTelemetry AWS Java SDK instrumentation.
+
+_Initialization Workflow_
+
+1. OpenTelemetry Agent starts
+   - Loads default instrumentations
+   - Loads aws-sdk instrumentation from opentelemetry-java-instrumentation
+   - Registers **TracingExecutionInterceptor** (order = 0)
+2. Scans for other SPI implementations
+   - Finds ADOT’s **AdotAwsSdkInstrumentationModule**
+   - Registers **AdotAwsSdkTracingExecutionInterceptor** (order > 0)
+
+### AWS SDK v2 Instrumentation Summary
+
+**AdotAwsSdkInstrumentationModule**
+
+The AdotAwsSdkInstrumentationModule registers the AdotAwsSdkTracingExecutionInterceptor in `registerHelperResources`.
+
+Key aspects of interceptor registration:
+- AWS SDK's ExecutionInterceptor loads global interceptors from files named '/software/amazon/awssdk/global/handlers/execution.interceptors' in the classpath
+- Interceptors are executed in the order they appear in the classpath - earlier entries run first
+- `order` method ensures ADOT instrumentation runs after OpenTelemetry's base instrumentation, maintaining proper sequence of interceptor registration in AWS SDK classpath
+
+**AdotAwsSdkTracingExecutionInterceptor**
+
+The AdotAwsSdkTracingExecutionInterceptor hooks onto OpenTelemetry's spans during specific phases of the SDK request and response life cycle. These hooks are strategically chosen to ensure proper ordering of attribute injection.
+
+1. `beforeTransmission`: the latest point where the SDK request can be obtained after it is modified by the upstream's interceptor
+2. `modifyResponse`: the latest point to access the SDK response before the span closes in the upstream afterExecution method
+
+_**Important Note:**_
+The upstream interceptor closes the span in `afterExecution`. That hook is inaccessible for span modification.
+`modifyResponse` is our final hook point, giving us access to both the fully processed response and active span.
+
+

instrumentation/aws-sdk/build.gradle.kts

@@ -0,0 +1,27 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+plugins {
+  java
+  id("com.gradleup.shadow")
+}
+
+base.archivesBaseName = "aws-instrumentation-aws-sdk"
+
+dependencies {
+  compileOnly("io.opentelemetry.javaagent:opentelemetry-javaagent-extension-api")
+  compileOnly("software.amazon.awssdk:aws-core:2.2.0")
+  compileOnly("net.bytebuddy:byte-buddy")
+}

instrumentation/aws-sdk/src/main/java/software/amazon/opentelemetry/javaagent/instrumentation/awssdk_v2_2/AdotAwsSdkInstrumentationModule.java

@@ -0,0 +1,88 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.opentelemetry.javaagent.instrumentation.awssdk_v2_2;
+
+import static io.opentelemetry.javaagent.extension.matcher.AgentElementMatchers.hasClassesNamed;
+import static net.bytebuddy.matcher.ElementMatchers.named;
+
+import io.opentelemetry.javaagent.extension.instrumentation.HelperResourceBuilder;
+import io.opentelemetry.javaagent.extension.instrumentation.InstrumentationModule;
+import io.opentelemetry.javaagent.extension.instrumentation.TypeInstrumentation;
+import io.opentelemetry.javaagent.extension.instrumentation.TypeTransformer;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import net.bytebuddy.description.type.TypeDescription;
+import net.bytebuddy.matcher.ElementMatcher;
+
+public class AdotAwsSdkInstrumentationModule extends InstrumentationModule {
+
+  public AdotAwsSdkInstrumentationModule() {
+    super("aws-sdk-adot", "aws-sdk-2.2-adot");
+  }
+
+  @Override
+  public int order() {
+    // Ensure this runs after OTel (> 0)
+    return 99;
+  }
+
+  @Override
+  public List<String> getAdditionalHelperClassNames() {
+    return Arrays.asList(
+        "software.amazon.opentelemetry.javaagent.instrumentation.awssdk_v2_2.AdotAwsSdkTracingExecutionInterceptor");
+  }
+
+  /**
+   * Registers resource file containing reference to our {@link
+   * AdotAwsSdkTracingExecutionInterceptor} with SDK's service loading mechanism. The 'order' method
+   * ensures this interceptor is registered after upstream. Interceptors are executed in the order
+   * they appear in the classpath.
+   *
+   * @see <a
+   *     href="https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/release/v2.11.x/instrumentation/aws-sdk/aws-sdk-2.2/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/awssdk/v2_2/AwsSdkInstrumentationModule.java#L27">reference</a>
+   */
+  @Override
+  public void registerHelperResources(HelperResourceBuilder helperResourceBuilder) {
+    helperResourceBuilder.register(
+        "software/amazon/awssdk/global/handlers/execution.interceptors",
+        "software/amazon/awssdk/global/handlers/execution.interceptors.adot");
+  }
+
+  @Override
+  public ElementMatcher.Junction<ClassLoader> classLoaderMatcher() {
+    return hasClassesNamed("software.amazon.awssdk.core.interceptor.ExecutionInterceptor");
+  }
+
+  @Override
+  public List<TypeInstrumentation> typeInstrumentations() {
+    return Collections.singletonList(new ResourceInjectingTypeInstrumentation());
+  }
+
+  public static class ResourceInjectingTypeInstrumentation implements TypeInstrumentation {
+    @Override
+    public ElementMatcher<TypeDescription> typeMatcher() {
+      // SdkClient is the base interface for all AWS SDK clients. Type matching against it ensures
+      // our interceptor is injected as soon as any AWS SDK client is initialized.
+      return named("software.amazon.awssdk.core.SdkClient");
+    }
+
+    @Override
+    public void transform(TypeTransformer transformer) {
+      // Empty as we use ExecutionInterceptor
+    }
+  }
+}

instrumentation/aws-sdk/src/main/java/software/amazon/opentelemetry/javaagent/instrumentation/awssdk_v2_2/AdotAwsSdkTracingExecutionInterceptor.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.opentelemetry.javaagent.instrumentation.awssdk_v2_2;
+
+import software.amazon.awssdk.core.SdkResponse;
+import software.amazon.awssdk.core.interceptor.*;
+
+public class AdotAwsSdkTracingExecutionInterceptor implements ExecutionInterceptor {
+
+  // This is the latest point we can obtain the Sdk Request after it is modified by the upstream
+  // TracingInterceptor. It ensures upstream handles the request and applies its changes first.
+  @Override
+  public void beforeTransmission(
+      Context.BeforeTransmission context, ExecutionAttributes executionAttributes) {}
+
+  // This is the latest point we can obtain the Sdk Response before span completion in upstream's
+  // afterExecution. This ensures we capture attributes from the final, fully modified response
+  // after all upstream interceptors have processed it.
+  @Override
+  public SdkResponse modifyResponse(
+      Context.ModifyResponse context, ExecutionAttributes executionAttributes) {
+
+    return context.response();
+  }
+}

instrumentation/aws-sdk/src/main/resources/META-INF/services/io.opentelemetry.javaagent.extension.instrumentation.InstrumentationModule

@@ -0,0 +1 @@
+software.amazon.opentelemetry.javaagent.instrumentation.awssdk_v2_2.AdotAwsSdkInstrumentationModule

instrumentation/aws-sdk/src/main/resources/software/amazon/awssdk/global/handlers/execution.interceptors.adot

@@ -0,0 +1 @@
+software.amazon.opentelemetry.javaagent.instrumentation.awssdk_v2_2.AdotAwsSdkTracingExecutionInterceptor

otelagent/build.gradle.kts

@@ -60,6 +60,7 @@ dependencies {
 
   javaagentLibs(project(":awsagentprovider"))
   javaagentLibs(project(":instrumentation:log4j-2.13.2"))
+  javaagentLibs(project(":instrumentation:aws-sdk"))
   javaagentLibs(project(":instrumentation:logback-1.0"))
   javaagentLibs(project(":instrumentation:jmx-metrics"))
 }

settings.gradle.kts

@@ -44,6 +44,7 @@ include(":dependencyManagement")
 include(":instrumentation:logback-1.0")
 include(":instrumentation:log4j-2.13.2")
 include(":instrumentation:jmx-metrics")
+include("instrumentation:aws-sdk")
 include(":otelagent")
 include(":smoke-tests:fakebackend")
 include(":smoke-tests:runner")