+ * The primary supported Arn format is:
+ *
+ *
+ * arn::<partition>::<service>::<region>::<account>::<resource>
+ *
+ *
+ *
+ * {@link #resourceAsString()} returns everything after the account section of the Arn + * as a single string. + * + *
+ * However, the following Arn formats are supported where the values are present and well + * formatted through {@link #resource()}: + * + *
+ * arn:<partition>:<service>:<region>:<account>:<resourcetype>/resource + * arn:<partition>:<service>:<region>:<account>:<resourcetype>/resource/qualifier + * arn:<partition>:<service>:<region>:<account>:<resourcetype>/resource:qualifier + * arn:<partition>:<service>:<region>:<account>:<resourcetype>:resource + * arn:<partition>:<service>:<region>:<account>:<resourcetype>:resource:qualifier + *+ * + * {@link #resource()} returns a {@link ArnResource} which has access + * to {@link ArnResource#resourceType()}, {@link ArnResource#resource()} and + * {@link ArnResource#qualifier()}. + * + *
+ * To parse an Arn from a string use Arn.fromString(). To convert an Arn to it's + * string representation use Arn.toString(). + * + *
+ * For instance, for a string s, containing a well-formed Arn the + * following should always be true: + * + *
+ * Arn theArn = Arn.fromString(s); + * s.equals(theArn.toString()); + *+ * + * @see ArnResource + */ +@SdkPublicApi +public final class Arn implements ToCopyableBuilder
+ * If {@link #resourceType} is not present, {@link #resource} will return the entire resource
+ * as a string the same as {@link Arn#resource()}.
+ *
+ * @see Arn
+ */
+@SdkPublicApi
+public final class ArnResource implements ToCopyableBuilder
+ * Supports fields separated by either ":" or "/".
+ *
+ *
+ * For legacy AWS Arns not following the resourceType:resource:qualifier pattern,
+ * the qualifier field will contain everything after the first two sections separated
+ * by either ":" or "/".
+ *
+ * @param resource - The resource string to parse.
+ * @return {@link ArnResource}
+ */
+ public static ArnResource fromString(String resource) {
+ Character splitter = StringUtils.findFirstOccurrence(resource, ':', '/');
+
+ if (splitter == null) {
+ return ArnResource.builder().resource(resource).build();
+ }
+
+ int resourceTypeColonIndex = resource.indexOf(splitter);
+
+ ArnResource.Builder builder = ArnResource.builder().resourceType(resource.substring(0, resourceTypeColonIndex));
+ int resourceColonIndex = resource.indexOf(splitter, resourceTypeColonIndex);
+ int qualifierColonIndex = resource.indexOf(splitter, resourceColonIndex + 1);
+ if (qualifierColonIndex < 0) {
+ builder.resource(resource.substring(resourceTypeColonIndex + 1));
+ } else {
+ builder.resource(resource.substring(resourceTypeColonIndex + 1, qualifierColonIndex));
+ builder.qualifier(resource.substring(qualifierColonIndex + 1));
+ }
+
+ return builder.build();
+ }
+
+ @Override
+ public String toString() {
+ return this.resourceType
+ + ":"
+ + this.resource
+ + ":"
+ + this.qualifier;
+ }
+
+ @Override
+ public boolean equals(Object o) {
+ if (this == o) {
+ return true;
+ }
+ if (o == null || getClass() != o.getClass()) {
+ return false;
+ }
+
+ ArnResource that = (ArnResource) o;
+
+ if (!Objects.equals(resourceType, that.resourceType)) {
+ return false;
+ }
+ if (!Objects.equals(resource, that.resource)) {
+ return false;
+ }
+ return Objects.equals(qualifier, that.qualifier);
+ }
+
+ @Override
+ public int hashCode() {
+ int result = resourceType != null ? resourceType.hashCode() : 0;
+ result = 31 * result + (resource != null ? resource.hashCode() : 0);
+ result = 31 * result + (qualifier != null ? qualifier.hashCode() : 0);
+ return result;
+ }
+
+ @Override
+ public Builder toBuilder() {
+ return builder()
+ .resource(resource)
+ .resourceType(resourceType)
+ .qualifier(qualifier);
+ }
+
+
+ public interface Builder extends CopyableBuilder Default: 1024 bytes. Default: 64000 bytes (64KB).
+ * This request includes signed AND unsigned headers.
+ */
+ public SdkHttpRequest httpRequest() {
+ return httpRequest;
+ }
+
+ @Override
+ public boolean equals(Object o) {
+ if (this == o) {
+ return true;
+ }
+ if (o == null || getClass() != o.getClass()) {
+ return false;
+ }
+
+ PresignedRequest that = (PresignedRequest) o;
+
+ if (isBrowserExecutable != that.isBrowserExecutable) {
+ return false;
+ }
+ if (!expiration.equals(that.expiration)) {
+ return false;
+ }
+ if (!signedHeaders.equals(that.signedHeaders)) {
+ return false;
+ }
+ if (signedPayload != null ? !signedPayload.equals(that.signedPayload) : that.signedPayload != null) {
+ return false;
+ }
+ return httpRequest.equals(that.httpRequest);
+ }
+
+ @Override
+ public int hashCode() {
+ int result = expiration.hashCode();
+ result = 31 * result + (isBrowserExecutable ? 1 : 0);
+ result = 31 * result + signedHeaders.hashCode();
+ result = 31 * result + (signedPayload != null ? signedPayload.hashCode() : 0);
+ result = 31 * result + httpRequest.hashCode();
+ return result;
+ }
+
+ @SdkPublicApi
+ public interface Builder {
+ /**
+ * Configure the exact SERVICE time that the request will expire. After this time, attempting to execute the request
+ * will fail.
+ */
+ Builder expiration(Instant expiration);
+
+ /**
+ * Configure whether the url returned by the url method can be executed in a browser.
+ */
+ Builder isBrowserExecutable(Boolean isBrowserExecutable);
+
+ /**
+ * Configure the subset of headers that were signed, and MUST be included in the presigned request to prevent
+ * the request from failing.
+ */
+ Builder signedHeaders(Map
+ * A metric can be tagged with multiple categories. Clients can enable/disable metric collection
+ * at a {@link MetricCategory} level.
+ */
+@SdkPublicApi
+public enum MetricCategory {
+ /**
+ * Metrics collected by the core SDK are classified under this category.
+ */
+ CORE("Core"),
+
+ /**
+ * Metrics collected at the http client level are classified under this category.
+ */
+ HTTP_CLIENT("HttpClient"),
+
+ /**
+ * Metrics specified by the customer should be classified under this category.
+ */
+ CUSTOM("Custom"),
+
+ /**
+ * This is an umbrella category (provided for convenience) that records metrics belonging to every category
+ * defined in this enum. Clients who wish to collect lot of SDK metrics data should use this.
+ *
+ * Note: Enabling this option along with {@link MetricLevel#TRACE} is verbose and can be expensive based on the platform
+ * the metrics are uploaded to. Please make sure you need all this data before using this category.
+ */
+ ALL("All");
+
+ private final String value;
+
+ MetricCategory(String value) {
+ this.value = value;
+ }
+
+ public String getValue() {
+ return value;
+ }
+
+ /**
+ * Create a {@link MetricCategory} from the given String value. This method is case insensitive.
+ *
+ * @param value the value to create the {@link MetricCategory} from
+ * @return A {@link MetricCategory} if the given {@link #value} matches one of the enum values.
+ * Otherwise throws {@link IllegalArgumentException}
+ */
+ public static MetricCategory fromString(String value) {
+ for (MetricCategory mc : MetricCategory.values()) {
+ if (mc.value.equalsIgnoreCase(value)) {
+ return mc;
+ }
+ }
+
+ throw new IllegalArgumentException("MetricCategory cannot be created from value: " + value);
+ }
+}
diff --git a/core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricCollection.java b/core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricCollection.java
new file mode 100644
index 000000000000..5eb4a031de98
--- /dev/null
+++ b/core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricCollection.java
@@ -0,0 +1,69 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * 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.awssdk.metrics;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.stream.Stream;
+import java.util.stream.StreamSupport;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+
+/**
+ * An immutable collection of metrics.
+ */
+@SdkPublicApi
+public interface MetricCollection extends Iterable
+ * Calling {@code collect()} prevents further invocations of {@link #reportMetric(SdkMetric, Object)}.
+ * @return The collected metrics.
+ */
+ MetricCollection collect();
+
+ static MetricCollector create(String name) {
+ return DefaultMetricCollector.create(name);
+ }
+}
diff --git a/core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricLevel.java b/core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricLevel.java
new file mode 100644
index 000000000000..5c87d9805a68
--- /dev/null
+++ b/core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricLevel.java
@@ -0,0 +1,49 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * 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.awssdk.metrics;
+
+import software.amazon.awssdk.annotations.SdkPublicApi;
+
+/**
+ * The {@code MetricLevel} associated with a {@link SdkMetric}, similar to log levels, defines the 'scenario' in which the metric
+ * is useful. This makes it easy to reduce the cost of metric publishing (e.g. by setting it to {@link #INFO}), and then increase
+ * it when additional data level is needed for debugging purposes (e.g. by setting it to {@link #TRACE}.
+ */
+@SdkPublicApi
+public enum MetricLevel {
+ /**
+ * The metric level that includes every other metric level, as well as some highly-technical metrics that may only be useful
+ * in very specific performance or failure scenarios.
+ */
+ TRACE,
+
+ /**
+ * The "default" metric level that includes metrics that are useful for identifying why errors or performance issues
+ * are occurring within the SDK. This excludes technical metrics that are only useful in very specific performance or failure
+ * scenarios.
+ */
+ INFO,
+
+ /**
+ * Includes metrics that report when API call errors are occurring within the SDK. This does not include all
+ * of the information that may be generally useful when debugging why errors are occurring (e.g. latency).
+ */
+ ERROR;
+
+ public boolean includesLevel(MetricLevel level) {
+ return this.compareTo(level) <= 0;
+ }
+}
diff --git a/core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricPublisher.java b/core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricPublisher.java
new file mode 100644
index 000000000000..78fd56616928
--- /dev/null
+++ b/core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricPublisher.java
@@ -0,0 +1,67 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * 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.awssdk.metrics;
+
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.annotations.ThreadSafe;
+import software.amazon.awssdk.utils.SdkAutoCloseable;
+
+/**
+ * Interface to report and publish the collected SDK metric events to external
+ * sources.
+ *
+ * Conceptually, a publisher receives a stream of {@link MetricCollection} objects
+ * overs its lifetime through its {@link #publish(MetricCollection)} )} method.
+ * Implementations are then free further aggregate these events into sets of
+ * metrics that are then published to some external system for further use.
+ * As long as a publisher is not closed, then it can receive {@code
+ * MetricCollection} objects at any time. In addition, as the SDK makes use of
+ * multithreading, it's possible that the publisher is shared concurrently by
+ * multiple threads, and necessitates that all implementations are threadsafe.
+ *
+ * The SDK may invoke methods on the interface from multiple threads
+ * concurrently so implementations must be threadsafe.
+ */
+@ThreadSafe
+@SdkPublicApi
+public interface MetricPublisher extends SdkAutoCloseable {
+ /**
+ * Notify the publisher of new metric data. After this call returns, the
+ * caller can safely discard the given {@code metricCollection} instance if it
+ * no longer needs it. Implementations are strongly encouraged to complete
+ * any further aggregation and publishing of metrics in an asynchronous manner to
+ * avoid blocking the calling thread.
+ *
+ * With the exception of a {@code null} {@code metricCollection}, all
+ * invocations of this method must return normally. This
+ * is to ensure that callers of the publisher can safely assume that even
+ * in situations where an error happens during publishing that it will not
+ * interrupt the calling thread.
+ *
+ * @param metricCollection The collection of metrics.
+ * @throws IllegalArgumentException If {@code metricCollection} is {@code null}.
+ */
+ void publish(MetricCollection metricCollection);
+
+ /**
+ * {@inheritDoc}
+ *
+ * Important: Implementations must block the calling thread until all
+ * pending metrics are published and any resources acquired have been freed.
+ */
+ @Override
+ void close();
+}
diff --git a/core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricRecord.java b/core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricRecord.java
new file mode 100644
index 000000000000..2ec0cbcb5db2
--- /dev/null
+++ b/core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricRecord.java
@@ -0,0 +1,34 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * 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.awssdk.metrics;
+
+import software.amazon.awssdk.annotations.SdkPublicApi;
+
+/**
+ * A container associating a metric and its value.
+ */
+@SdkPublicApi
+public interface MetricRecord