Release/v2.11.3 #1146
Merged
Release/v2.11.3 #1146
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
This PR is similar to aws-observability#1111, as it sets a base SPI implementation for AWS SDK v1.11. ### Issue 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 v1.11 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 v1.11 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 handler through AdotAwsSdkClientInstrumentation class in `typeInstrumentations` method 2. **AdotAwsSdkClientInstrumentation** - AdotAwsSdkClientAdvice registers our handler only if the upstream aws-sdk span is enabled (i.e. it checks if the upstream handler is present when an AWS SDK client is initialized). 3. **AdotAwsSdkTracingRequestHandler** - Extends AWS SDK's `RequestHandler2` - Hooks into key SDK lifecycle points: - `beforeRequest`: Captures final SDK request after upstream modifications - `afterAttempt`: Processes response before span closure in upstream - Will be used to enriches spans - Acts as central coordinator for all the awssdk_v1_11 components 4. **Resources Folder** - Registers the v1.11 AdotAwsSdkInstrumentationModule into OTel's SPI extension classpath in META-INF/services ### 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** - `beforeRequest`: Last point to access modified request - `afterAttempt`: Final opportunity to enrich span before closure ### 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 By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
Note: This is a continuation of aws-observability#1111 #### Description of Changes This implementation builds on the foundation established in PR aws-observability#1111, transforming the structural setup into a fully functional SPI-based solution that will replace our current patching approach. This PR does not change the current ADOT functionality because patches have not been removed. The next/final PR for v2.2 will remove the patches for aws-sdk-2.2 and have unit tests to ensure correct SPI functionality and behaviour. The final PR will also pass all the contract-tests once patches are removed. #### Changes include: - Migration of patched files into proper package structure: NOTE: We are not copying entire files from upstream. Instead, we only migrated the new components that were added by our patches and the methods that use these AWS-specific components. I deliberately removed any code that was untouched by our patches to avoid duplicating upstream instrumentation code. This selective migration ensures we maintain only our AWS-specific additions while letting OTel handle its base functionality. - `AwsExperimentalAttributes` - [patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch#L2587) creates new class - `AwsSdkRequest` - [patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch#L2673) on [this otel file](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/release/v2.11.x/instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal/AwsSdkRequest.java) - `AwsSdkRequestType` - [patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch#L2751) on [this otel file](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/release/v2.11.x/instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal/AwsSdkRequestType.java) - `BedrockJsonParser` - [patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch#L2860) creates new class - `FieldMapper` - [patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch#L3145) on [this otel file](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/release/v2.11.x/instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal/FieldMapper.java) - `Serializer` - [patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch#L3164) on [this otel file](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/release/v2.11.x/instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal/Serializer.java) - `BedrockJsonParserTest` - [patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch#L3474) creates new class - Setup of dependent files directly copied from upstream aws-sdk: - `MethodHandleFactory` - copy-pasted from [here](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/release/v2.11.x/instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal/MethodHandleFactory.java) - `FieldMapping` - copy-pasted from [here](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/release/v2.11.x/instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal/FieldMapping.java) - `AwsJsonProtocolFactoryAccess` - copy-pasted from [here](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/release/v2.11.x/instrumentation/aws-sdk/aws-sdk-2.2/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v2_2/internal/AwsJsonProtocolFactoryAccess.java) These added files: - Access and modify span attributes - Provide consistent formatting tools for span attributes - Can be updated at our convenience if needed The classes we copied from upstream are just helper utilities that make it easier to inject span attributes during instrumentation. They're not core functionality that needs to stay in sync with upstream changes, rather standalone utilities that support our simpler, independent instrumentation without creating version lock-in. They're independent of OTel's core functionality, so we don't face the same version dependency issues we had with patching. We're just following upstream's structure for consistency. #### OTel attribution for copied files The 3 coped files have the OTel header included in them. This follows section 4 a)-c) in the ADOT [LICENSE](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/LICENSE#L89) #### Testing - Existing functionality verified - Contract tests passing - Build successful #### Related - Skeleton PR for aws-sdk v2.2: aws-observability#1111 - Replaces patch: [current patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch) By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license. --------- Co-authored-by: Thomas Pierce <[email protected]>
Note: This is a continuation of aws-observability#1115 ### Description of Changes This implementation builds on the foundation established in PR aws-observability#1115, transforming the structural setup into a fully functional SPI-based solution that will replace our current patching approach. This PR does not change the current ADOT functionality because patches have not been removed. The next/final PR for v1.11 will remove the patches for aws-sdk-1.11 and have unit tests to ensure correct SPI functionality and behaviour. The final PR will also pass all the contract-tests once patches are removed. #### Changes include: - Migration of patched files into proper package structure: NOTE: We are not copying entire files from upstream. Instead, we only migrated the new components that were added by our patches and the methods that use these AWS-specific components. I deliberately removed any code that was untouched by our patches to avoid duplicating upstream instrumentation code. This selective migration ensures we maintain only our AWS-specific additions while letting OTel handle its base functionality. - `AwsBedrockResourceType` - [patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch#L224) creates new class - `AwsExperimentalAttributes` - [patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch#L362) on [this otel file](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/release/v2.11.x/instrumentation/aws-sdk/aws-sdk-1.11/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v1_11/AwsExperimentalAttributes.java) - `AwsSdkExperimentalAttributesExtractor` - [patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch#L408) on [this otel file](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/release/v2.11.x/instrumentation/aws-sdk/aws-sdk-1.11/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v1_11/AwsSdkExperimentalAttributesExtractor.java) - `BedrockJsonParser` - [patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch#L655) creates new class - `RequestAccess` - [patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch#L927) on [this otel file](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/release/v2.11.x/instrumentation/aws-sdk/aws-sdk-1.11/library/src/main/java/io/opentelemetry/instrumentation/awssdk/v1_11/RequestAccess.java) - `BedrockJsonParserTest` - [patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch#L1461) creates new class These added files: - Access and modify span attributes - Provide consistent formatting tools for span attributes - Can be updated at our convenience if needed ### Testing - Existing functionality verified - Contract tests passing - Build successful ### Related - Skeleton PR for aws-sdk v1.11: aws-observability#1115 - Replaces patch: [current patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch) By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license. --------- Co-authored-by: Thomas Pierce <[email protected]>
…rvability#1120) This is the final PR for the SPI aws-sdk instrumentation. It removes the [opentelemetry-java-instrumentation](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch) patch and adds comprehensive unit test coverage for AWS experimental attributes in both AWS SDK v1.11 and v2.2 instrumentation packages. The v2.2 package introduces 29 new experimental attributes while v1.11 adds 23 new experimental attributes. All attributes are now tested through unit tests and/or contract tests. ### Description of changes: #### AWS SDK v2.2 (awssdk_v2_2) New attributes being tested: 1. AWS_BUCKET_NAME - testS3ExperimentalAttributes() & contract tests 2. AWS_QUEUE_URL - testSqsExperimentalAttributes() & contract tests 3. AWS_QUEUE_NAME - contract tests 4. AWS_STREAM_NAME - testKinesisExperimentalAttributes() & contract tests 5. AWS_STREAM_ARN - testKinesisExperimentalAttributes() & contract tests 6. AWS_TABLE_NAME - testDynamoDbExperimentalAttributes() 7. AWS_GUARDRAIL_ID - contract tests 8. AWS_GUARDRAIL_ARN - contract tests 9. AWS_AGENT_ID - testBedrockAgentExperimentalAttributes() & contract tests 10. AWS_DATA_SOURCE_ID - testBedrockDataSourceExperimentalAttributes() & contract tests 11. AWS_KNOWLEDGE_BASE_ID - testBedrockKnowledgeBaseExperimentalAttributes() & contract tests 12. GEN_AI_MODEL - testBedrockExperimentalAttributes() & contract tests 13. GEN_AI_SYSTEM - contract tests 14. GEN_AI_REQUEST_MAX_TOKENS - testBedrockExperimentalAttributes() & contract tests 15. GEN_AI_REQUEST_TEMPERATURE - testBedrockExperimentalAttributes() & contract tests 16. GEN_AI_REQUEST_TOP_P - contract tests 17. GEN_AI_RESPONSE_FINISH_REASONS - contract tests 18. GEN_AI_USAGE_INPUT_TOKENS - contract tests 19. GEN_AI_USAGE_OUTPUT_TOKENS - contract tests 20. AWS_STATE_MACHINE_ARN - testStepFunctionExperimentalAttributes() & contract tests 21. AWS_STEP_FUNCTIONS_ACTIVITY_ARN - testStepFunctionExperimentalAttributes() & contract tests 22. AWS_SNS_TOPIC_ARN - testSnsExperimentalAttributes() & contract tests 23. AWS_SECRET_ARN - testSecretsManagerExperimentalAttributes() & contract tests 24. AWS_LAMBDA_NAME - testLambdaExperimentalAttributes() 25. AWS_LAMBDA_ARN - testLambdaArnExperimentalAttribute() 26. AWS_LAMBDA_RESOURCE_ID - testLambdaResourceIdExperimentalAttribute() 27. AWS_TABLE_ARN - testTableArnExperimentalAttribute() 28. AWS_AUTH_ACCESS_KEY - testAuthAccessKeyExperimentalAttribute() 29. AWS_AUTH_REGION - testAuthRegionExperimentalAttribute() - Tests leverage AWS SDK v2's getValueForField() API for clean, mockable attribute extraction - Includes comprehensive testing for: - Core AWS services (S3, DynamoDB, SQS, SNS, Kinesis, Lambda, Step Functions, Secrets Manager) - Bedrock Gen AI attributes with JSON parsing validation - Bedrock resource attributes (Agent, Knowledge Base, Data Source) - Authentication attributes (access key, region) ### AWS SDK v1.11 (awssdk_v1_11) New attributes being tested: 1. AWS_STREAM_ARN - testKinesisExperimentalAttributes() & contract tests 2. AWS_TABLE_ARN - testTableArnExperimentalAttributes() (Service identification only) 3. AWS_AGENT_ID - contract tests 4. AWS_KNOWLEDGE_BASE_ID - contract tests 5. AWS_DATA_SOURCE_ID - contract tests 6. AWS_GUARDRAIL_ID - testBedrockGuardrailAttributes() (Service identification only) & contract tests 7. AWS_GUARDRAIL_ARN - testBedrockGuardrailAttributes() (Service identification only) & contract tests 8. AWS_BEDROCK_RUNTIME_MODEL_ID - testBedrockRuntimeAttributes() (Service identification only) & contract tests 9. AWS_BEDROCK_SYSTEM - contract tests 10. GEN_AI_REQUEST_MAX_TOKENS - contract tests 11. GEN_AI_REQUEST_TEMPERATURE - contract tests 12. GEN_AI_REQUEST_TOP_P - contract tests 13. GEN_AI_RESPONSE_FINISH_REASONS - contract tests 14. GEN_AI_USAGE_INPUT_TOKENS - contract tests 15. GEN_AI_USAGE_OUTPUT_TOKENS - contract tests 16. AWS_STATE_MACHINE_ARN - testStepFunctionsExperimentalAttributes() & contract tests 17. AWS_STEP_FUNCTIONS_ACTIVITY_ARN - contract tests 18. AWS_SNS_TOPIC_ARN - testSnsExperimentalAttributes() & contract tests 19. AWS_SECRET_ARN - testSecretsManagerExperimentalAttributes() (Service identification only) & contract tests 20. AWS_LAMBDA_NAME - testLambdaNameExperimentalAttributes() 21. AWS_LAMBDA_ARN - testLambdaArnExperimentalAttributes() 22. AWS_LAMBDA_RESOURCE_ID - testLambdaResourceIdExperimentalAttributes() (Service identification only) 23. AWS_AUTH_ACCESS_KEY - testAuthAccessKeyAttributes() *V1.11 is harder to test:* V1.11 uses Java reflection to dynamically find and call methods like getFunctionName() on AWS request objects at runtime. This creates several testing challenges: - Mock Method Mismatch: When you mock an AWS request object, it doesn't have the actual methods that reflection is trying to find. The reflection silently fails and returns null, making tests pass even though no attributes were extracted. - Class Dependencies: To test properly, you'd need real AWS SDK classes instead of mocks, creating tight coupling between tests and external dependencies. - Nested Object Complexity: Many attributes require traversing nested properties, which means mocking entire object graphs with proper method chains. Contract tests sidestep these issues by using real AWS SDK objects against LocalStack, testing the complete end-to-end flow including actual reflection behavior without the complexity of mocking Java's reflection system. ### Related - PRs for aws-sdk v1.11: aws-observability#1115 and aws-observability#1117 - PRs for aws-sdk v2.2: aws-observability#1111 and aws-observability#1113 - Replaces patch: [current patch](https://github.com/aws-observability/aws-otel-java-instrumentation/blob/main/.github/patches/opentelemetry-java-instrumentation.patch) By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license. # Conflicts: # .github/patches/opentelemetry-java-instrumentation.patch # dependencyManagement/build.gradle.kts # lambda-layer/patches/aws-otel-java-instrumentation.patch # lambda-layer/patches/opentelemetry-java-instrumentation.patch
liustve
previously approved these changes
Aug 14, 2025
majanjua-amzn
previously approved these changes
Aug 14, 2025
thpierce
previously approved these changes
Aug 14, 2025
*Description of changes:* Builds are failing image scanning for `CVE-2025-55163` which recently was added as a vulnerability. GHSA-prj3-ccx8-p6x4 Should revert this once we upgrade our aws-sdk dependency to version that has this PR added: aws/aws-sdk-java-v2#6344 By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license. --------- Co-authored-by: Thomas Pierce <[email protected]>
anahatAWS
dismissed stale reviews from thpierce, majanjua-amzn, and liustve
via
529bebe
liustve
approved these changes
Aug 14, 2025
thpierce
approved these changes
Aug 14, 2025
majanjua-amzn
approved these changes
Aug 14, 2025
liustve
merged commit 8c8b717
into
aws-observability:release/v2.11.x
7 of 8 checks passed
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description of changes:
Merges changes from mainline to v2.11.3
Namely: #1111 #1115 #1113 #1117 and #1120
Steps followed:
aws-otel-java-instrumentationreporelease/2.11.xrelease/2.11.3based offrelease/2.11.x(git checkout -b release/2.11.3)git cherry-pick 572215e ac3c0c7 9a76dda 8a3b772 25b2cd8./gradlew dependencyUpdatesBy submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.