Expose S3 Request Metrics

[azkrishpy]

Issue #, if available:
#806
Description of changes:
Exposes S3 Request Metrics from the CRT S3 Client.

• S3RequestMetrics: Captures timing, request/response info, and error details for each S3 request attempt
• onTelemetry() callback: New method in S3MetaRequestResponseHandler invoked after each request completes
• ErrorType classification: Categorizes errors (SUCCESS, THROTTLING, SERVER_ERROR, CONFIGURED_TIMEOUT, IO, OTHER)

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

[azkrishpy]

Java SDK users can use a custom MetricPublisher that bridges CRT metrics to SDK's MetricCollection:

public class CrtMetricPublisher implements MetricPublisher {
    private final MetricPublisher delegate;

    public CrtMetricPublisher(MetricPublisher delegate) {
        this.delegate = delegate;
    }

    public void publishCrtMetrics(S3RequestMetrics crtMetrics) {
        MetricCollection collection = MetricCollection.builder()
            .name("S3Request")
            .creationTime(Instant.now())
            .putMetric(CoreMetric.API_CALL_DURATION, 
                Duration.ofNanos(crtMetrics.getApiCallDurationNs()))
            .putMetric(CoreMetric.SERVICE_ID, crtMetrics.getServiceId())
            .putMetric(CoreMetric.OPERATION_NAME, crtMetrics.getOperationName())
            .putMetric(CoreMetric.RETRY_COUNT, crtMetrics.getRetryCount())
            .putMetric(CoreMetric.AWS_REQUEST_ID, crtMetrics.getAwsRequestId())
            .putMetric(CoreMetric.AWS_EXTENDED_REQUEST_ID, crtMetrics.getAwsExtendedRequestId())
            .putMetric(CoreMetric.BACKOFF_DELAY_DURATION, 
                Duration.ofNanos(crtMetrics.getBackoffDelayDurationNs()))
            .putMetric(CoreMetric.SERVICE_CALL_DURATION, 
                Duration.ofNanos(crtMetrics.getServiceCallDurationNs()))
            .putMetric(CoreMetric.SIGNING_DURATION, 
                Duration.ofNanos(crtMetrics.getSigningDurationNs()))
            .build();

        delegate.publish(collection);
    }

    @Override
    public void publish(MetricCollection metricCollection) {
        delegate.publish(metricCollection);
    }

    @Override
    public void close() {
        delegate.close();
    }
}

Usage

CrtMetricPublisher metricPublisher = new CrtMetricPublisher(
    LoggingMetricPublisher.create());

S3MetaRequestResponseHandler responseHandler = new S3MetaRequestResponseHandler() {
    @Override
    public void onTelemetry(S3RequestMetrics metrics) {
        metricPublisher.publishCrtMetrics(metrics);
    }

    @Override
    public void onFinished(S3FinishedResponseContext context) {
        // Handle completion
    }
};

S3MetaRequestOptions options = new S3MetaRequestOptions()
    .withMetaRequestType(MetaRequestType.GET_OBJECT)
    .withHttpRequest(httpRequest)
    .withResponseHandler(responseHandler);

try (S3MetaRequest request = client.makeMetaRequest(options)) {
    // Request executes, metrics published via onTelemetry callback
}

[azkrishpy]

The following metrics are not available from CRT for java since sdk has the information:

• CredentialsFetchDuration
• EndpointResolveDuration
• MarshallingDuration
• ServiceEndpoint

[zoewangg]

For multipart/ranged get requests, which request is this for? The first request? Same question for other metrics such as service call duration

[azkrishpy]

For both? Request metrics are made available for any request that involves communicating with S3. If it is a multipart request, each part gets its own metrics data. if the requests are ranged gets, each get gets its own metrics object.

CRT retries request (upload part, range-get) level failures up to 5 times and one of the metrics by definition requires an aggregation (API Call duration). API call duration would be zero for failures but the successful final attempt aggregates the duration correctly.

The rest of the metrics are unique by nature. Does this help?

[zoewangg]

What do you mean by partial execution? When is this invoked?

[azkrishpy]

When there are multiple parallelized request created for a single meta request, each request gets its own response with metrics. Although the meta request might not have been fully executed, the request might be complete and hence customers receive the metric data for that request. This is what I meant by partial execution of meta request.

[zoewangg]

Gotcha, can we update the documentation to make it more clear?

[zoewangg]

What about HTTP metrics like max connections, available connections, etc? https://github.com/aws/aws-sdk-java-v2/blob/master/http-client-spi/src/main/java/software/amazon/awssdk/http/HttpMetric.java#L48

[azkrishpy]

https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/metrics-list.html

the docs did not contain details of HTTP metrics being delivered to user so I had omitted the same. However, if necessary it is an easy change since the members are still privately available within the metrics object and I can expose additional public methods for access. Please do let me know if this is an issue. Thanks for the review!!

[zoewangg]

Yeah, if we can add HTTP metrics, that'd be great. They are super helpful for troubleshooting purposes