1 /* 2 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"). 5 * You may not use this file except in compliance with the License. 6 * A copy of the License is located at 7 * 8 * http://aws.amazon.com/apache2.0 9 * 10 * or in the "license" file accompanying this file. This file is distributed 11 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either 12 * express or implied. See the License for the specific language governing 13 * permissions and limitations under the License. 14 */ 15 16 package software.amazon.awssdk.core.metrics; 17 18 import java.net.URI; 19 import java.time.Duration; 20 import software.amazon.awssdk.annotations.SdkPublicApi; 21 import software.amazon.awssdk.core.async.AsyncResponseTransformer; 22 import software.amazon.awssdk.core.retry.RetryPolicy; 23 import software.amazon.awssdk.core.sync.ResponseTransformer; 24 import software.amazon.awssdk.metrics.MetricCategory; 25 import software.amazon.awssdk.metrics.MetricLevel; 26 import software.amazon.awssdk.metrics.SdkMetric; 27 28 @SdkPublicApi 29 public final class CoreMetric { 30 /** 31 * The unique ID for the service. This is present for all API call metrics. 32 */ 33 public static final SdkMetric<String> SERVICE_ID = 34 metric("ServiceId", String.class, MetricLevel.ERROR); 35 36 /** 37 * The name of the service operation being invoked. This is present for all 38 * API call metrics. 39 */ 40 public static final SdkMetric<String> OPERATION_NAME = 41 metric("OperationName", String.class, MetricLevel.ERROR); 42 43 /** 44 * True if the API call succeeded, false otherwise. 45 */ 46 public static final SdkMetric<Boolean> API_CALL_SUCCESSFUL = 47 metric("ApiCallSuccessful", Boolean.class, MetricLevel.ERROR); 48 49 /** 50 * The number of retries that the SDK performed in the execution of the request. 0 implies that the request worked the first 51 * time, and no retries were attempted. 52 */ 53 public static final SdkMetric<Integer> RETRY_COUNT = 54 metric("RetryCount", Integer.class, MetricLevel.ERROR); 55 56 /** 57 * The endpoint for the service. 58 */ 59 public static final SdkMetric<URI> SERVICE_ENDPOINT = 60 metric("ServiceEndpoint", URI.class, MetricLevel.ERROR); 61 62 /** 63 * The duration of the API call. This includes all call attempts made. 64 * 65 * <p>{@code API_CALL_DURATION ~= CREDENTIALS_FETCH_DURATION + MARSHALLING_DURATION + SUM_ALL(BACKOFF_DELAY_DURATION) + 66 * SUM_ALL(SIGNING_DURATION) + SUM_ALL(SERVICE_CALL_DURATION) + SUM_ALL(UNMARSHALLING_DURATION)} 67 */ 68 public static final SdkMetric<Duration> API_CALL_DURATION = 69 metric("ApiCallDuration", Duration.class, MetricLevel.INFO); 70 71 /** 72 * The duration of time taken to fetch signing credentials for the API call. 73 */ 74 public static final SdkMetric<Duration> CREDENTIALS_FETCH_DURATION = 75 metric("CredentialsFetchDuration", Duration.class, MetricLevel.INFO); 76 77 /** 78 * The duration of time taken to fetch signing credentials for the API call. 79 */ 80 public static final SdkMetric<Duration> TOKEN_FETCH_DURATION = 81 metric("TokenFetchDuration", Duration.class, MetricLevel.INFO); 82 83 /** 84 * The duration of time that the SDK has waited before this API call attempt, based on the 85 * {@link RetryPolicy#backoffStrategy()}. 86 */ 87 public static final SdkMetric<Duration> BACKOFF_DELAY_DURATION = 88 metric("BackoffDelayDuration", Duration.class, MetricLevel.INFO); 89 90 /** 91 * The duration of time taken to marshall the SDK request to an HTTP request. 92 */ 93 public static final SdkMetric<Duration> MARSHALLING_DURATION = 94 metric("MarshallingDuration", Duration.class, MetricLevel.INFO); 95 96 /** 97 * The duration of time taken to sign the HTTP request. 98 */ 99 public static final SdkMetric<Duration> SIGNING_DURATION = 100 metric("SigningDuration", Duration.class, MetricLevel.INFO); 101 102 /** 103 * The duration of time taken to connect to the service (or acquire a connection from the connection pool), send the 104 * serialized request and receive the initial response (e.g. HTTP status code and headers). This DOES NOT include the time 105 * taken to read the entire response from the service. 106 */ 107 public static final SdkMetric<Duration> SERVICE_CALL_DURATION = 108 metric("ServiceCallDuration", Duration.class, MetricLevel.INFO); 109 110 /** 111 * The duration of time taken to unmarshall the HTTP response to an SDK response. 112 * 113 * <p>Note: For streaming operations, this does not include the time to read the response payload. 114 */ 115 public static final SdkMetric<Duration> UNMARSHALLING_DURATION = 116 metric("UnmarshallingDuration", Duration.class, MetricLevel.INFO); 117 118 /** 119 * The request ID of the service request. 120 */ 121 public static final SdkMetric<String> AWS_REQUEST_ID = 122 metric("AwsRequestId", String.class, MetricLevel.INFO); 123 124 /** 125 * The extended request ID of the service request. 126 */ 127 public static final SdkMetric<String> AWS_EXTENDED_REQUEST_ID = 128 metric("AwsExtendedRequestId", String.class, MetricLevel.INFO); 129 130 /** 131 * The duration of time between from sending the HTTP request (including acquiring a connection) to the service, and 132 * receiving the first byte of the headers in the response. 133 */ 134 // Note: SERVICE_CALL_DURATION matches TTFB for sync, but *NOT* async. This appears to be a bug. 135 public static final SdkMetric<Duration> TIME_TO_FIRST_BYTE = 136 metric("TimeToFirstByte", Duration.class, MetricLevel.TRACE); 137 138 /** 139 * The duration of time between from sending the HTTP request (including acquiring a connection) to the service, and 140 * receiving the last byte of the response. 141 * <p> 142 * Note that for APIs that return streaming responses, this metric spans the time until the {@link ResponseTransformer} or 143 * {@link AsyncResponseTransformer} completes. 144 */ 145 public static final SdkMetric<Duration> TIME_TO_LAST_BYTE = 146 metric("TimeToLastByte", Duration.class, MetricLevel.TRACE); 147 148 /** 149 * The read throughput of the client, defined as {@code NumberOfResponseBytesRead / (TTLB - TTFB)}. This value is in bytes per 150 * second. 151 * <p> 152 * Note that this metric only measures the bytes read from within the {@link ResponseTransformer} or 153 * {@link AsyncResponseTransformer}. Data that is read outside the transformer (e.g. when the response stream is returned as 154 * the result of the transformer) is not included in the calculation. 155 */ 156 public static final SdkMetric<Double> READ_THROUGHPUT = 157 metric("ReadThroughput", Double.class, MetricLevel.TRACE); 158 159 /** 160 * The duration of time it took to resolve the endpoint used for the API call. 161 */ 162 public static final SdkMetric<Duration> ENDPOINT_RESOLVE_DURATION = 163 metric("EndpointResolveDuration", Duration.class, MetricLevel.INFO); 164 165 166 /** 167 * The type of error that occurred for a call attempt. 168 * <p> 169 * The following are possible values: 170 * <ul> 171 * <li>Throttling - The service responded with a throttling error.</li> 172 * <li>ServerError - The service responded with an error other than throttling.</li> 173 * <li>ClientTimeout - A client timeout occurred, either at the API call level, or API call attempt level.</li> 174 * <li>IO - An I/O error occurred.</li> 175 * <li>Other - Catch-all for other errors that don't fall into the above categories.</li> 176 * </ul> 177 * <p> 178 */ 179 public static final SdkMetric<String> ERROR_TYPE = 180 metric("ErrorType", String.class, MetricLevel.INFO); 181 CoreMetric()182 private CoreMetric() { 183 } 184 metric(String name, Class<T> clzz, MetricLevel level)185 private static <T> SdkMetric<T> metric(String name, Class<T> clzz, MetricLevel level) { 186 return SdkMetric.create(name, clzz, level, MetricCategory.CORE); 187 } 188 } 189