Adding attempt count to error message

[RanVaknin]

Motivation and Context

Improve debugging visibility by making attempt count immediately visible in exception messages. Currently, attempt information is only available through suppressed exceptions, requiring additional code to access. This change makes attempts visible directly in the exception message, matching behavior in other AWS SDKs.

Modifications

• Added attempt count tracking and message formatting in SdkException
• Added SdkDiagnostics class to handle the formatting of the Diagnostics clause in error messages.
• Modified AwsServiceException to include attempts in AWS error details
• Modified RetryableStageHelper to track and propagate attempt counts during retries

Testing

• Added new functional test ExceptionAttemptMessageBehaviorTest testing with different retry scenarios
• Modified existing tests in AwsServiceExceptionTest and SdkExceptionSerializationTest to verify attempt count behavior
• Added test cases in SdkExceptionMessageTest for new attempt count functionality

Visualization of changes:

Before change:

// non-retryable scenario
try {
    // request to a non-existent bucket
    s3Client.listObjects(g -> g.bucket("some-non-existent-bucket"));
} catch (AwsServiceException e) {
    System.out.println(e);
}
// outputs:
// NoSuchBucketException: The specified bucket does not exist (Service: S3, Status Code: 404, Request ID: abc123, Extended Request ID: xyzdef123456)


// retryable scenario
try {
    // request that might cause a retryable error (e.g., throttling)
    dynamoDbClient.getItem(...);
} catch (AwsServiceException e) {
    System.out.println(e);
}
// outputs:
// ThrottlingException: Rate of requests exceeds the allowed throughput (Service: DynamoDB, Status Code: 429, Request ID: abc123, Extended Request ID: xyzdef123456)
// Note: attempts only visible through e.getSuppressed()

After change:

// non-retryable scenario
try {
    // request to a non-existent bucket
    s3Client.listObjects(g -> g.bucket("some-non-existent-bucket"));
} catch (AwsServiceException e) {
    System.out.println(e);
}
// outputs:
// NoSuchBucketException: The specified bucket does not exist (Service: S3, Status Code: 404, Request ID: abc123, Extended Request ID: xyzdef123456) (SDK Diagnostics: numAttempts = 1)


// retryable scenario
try {
    // request that might cause a retryable error (e.g., throttling)
    dynamoDbClient.getItem(...);
} catch (AwsServiceException e) {
    System.out.println(e);
}
// outputs:
// ThrottlingException: Rate of requests exceeds the allowed throughput (Service: DynamoDB, Status Code: 429, Request ID: abc123, Extended Request ID: xyzdef123456) (SDK Diagnostics: numAttempts = 4)
// Note: attempts now visible directly in the exception message

Potential Impact:

Test or error handling code that relies on exact exception message matching might break as messages now include attempt count. We recommend using partial message matching for more resilient tests and error handling.

// may break
assertEquals("Resource not found", e.getMessage());
if (e.getMessage().equals("Resource not found")) { ... }

// more resilient approach
assertTrue(e.getMessage().contains("Resource not found"));

try {
    client.someOperation();
} catch (AwsServiceException e) {
	// may break
    if (e.getMessage().equals("Resource not found")) {
        handleNotFound();
    }
	// more resilient
    if (e.getMessage().contains("Resource not found")) {
        handleNotFound();
    }
}

[sonarqubecloud]

Quality Gate passed

Issues
13 New issues
0 Accepted issues

Measures
0 Security Hotspots
93.1% Coverage on New Code
0.8% Duplication on New Code

See analysis details on SonarQube Cloud

[L-Applin]

Maybe it's me that is confused, but test name says WithoutAttemptCount but we set numAttempt to 6?

[L-Applin]

Why do we need to cast here? Does the type return when calling .build() change? It should not change as it is a public API

[L-Applin]

coul you implement the ToCopyableBuilder interface here? with the build extending the Builder interface? You can look at EndpointDiscoveryEndpoint for an example

[L-Applin]

the builder instance returned should have the numAttempt of this instance

[L-Applin]

could you add default and throw new UnsupportedOperationException for this method and numAttempts()? As this is a public API, there is a small chance that users might extends this interface, and it would break them at compile time since they are not implementing these methods

[L-Applin]

same here did the thrown exception type changed?