Add Preview annotations for metrics related classes/methods

Author: dagnir

core/annotations/src/main/java/software/amazon/awssdk/annotations/SdkPreviewApi.java

@@ -0,0 +1,30 @@
+/*
+ * 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.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * Marker interface for preview and experimental APIs. Breaking changes may be
+ * introduced to elements marked as {@link SdkPreviewApi}. Users of the SDK
+ * should assume that anything annotated as preview will change or break, and
+ * <b>should not</b> use them in production.
+ */
+@Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD})
+@SdkProtectedApi
+public @interface SdkPreviewApi {
+}

core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/LoggingMetricPublisher.java

@@ -15,13 +15,17 @@
 
 package software.amazon.awssdk.metrics;
 
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.utils.Logger;
 
 /**
  * An implementation of {@link MetricPublisher} that writes all published metrics to the logs at the INFO level under the
  * {@code software.amazon.awssdk.metrics.LoggingMetricPublisher} namespace.
+ *
+ * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
  */
+@SdkPreviewApi
 @SdkPublicApi
 public final class LoggingMetricPublisher implements MetricPublisher {
     private static final Logger LOGGER = Logger.loggerFor(LoggingMetricPublisher.class);

core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricCategory.java

@@ -15,14 +15,18 @@
 
 package software.amazon.awssdk.metrics;
 
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 
 /**
  * A enum class representing the different types of metric categories in the SDK.
  * <p>
  * A metric can be tagged with multiple categories. Clients can enable/disable metric collection
  * at a {@link MetricCategory} level.
+ *
+ * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
  */
+@SdkPreviewApi
 @SdkPublicApi
 public enum MetricCategory {
     /**

core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricCollection.java

@@ -19,11 +19,15 @@
 import java.util.List;
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 
 /**
  * An immutable collection of metrics.
+ *
+ * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
  */
+@SdkPreviewApi
 @SdkPublicApi
 public interface MetricCollection extends Iterable<MetricRecord<?>> {
     /**

core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricCollector.java

@@ -16,12 +16,16 @@
 package software.amazon.awssdk.metrics;
 
 import software.amazon.awssdk.annotations.NotThreadSafe;
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.metrics.internal.DefaultMetricCollector;
 
 /**
  * Used to collect metrics reported by the SDK.
+ *
+ * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
  */
+@SdkPreviewApi
 @NotThreadSafe
 @SdkPublicApi
 public interface MetricCollector {

core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricLevel.java

@@ -15,13 +15,17 @@
 
 package software.amazon.awssdk.metrics;
 
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 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}.
+ *
+ * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
  */
+@SdkPreviewApi
 @SdkPublicApi
 public enum MetricLevel {
     /**

core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricPublisher.java

@@ -15,6 +15,7 @@
 
 package software.amazon.awssdk.metrics;
 
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.annotations.ThreadSafe;
 import software.amazon.awssdk.metrics.MetricCollection;
@@ -35,7 +36,10 @@
  * <p>
  * The SDK may invoke methods on the interface from multiple threads
  * concurrently so implementations must be threadsafe.
+ *
+ * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
  */
+@SdkPreviewApi
 @ThreadSafe
 @SdkPublicApi
 public interface MetricPublisher extends SdkAutoCloseable {

core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/MetricRecord.java

@@ -15,11 +15,15 @@
 
 package software.amazon.awssdk.metrics;
 
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 
 /**
  * A container associating a metric and its value.
+ *
+ * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
  */
+@SdkPreviewApi
 @SdkPublicApi
 public interface MetricRecord<T> {
     /**

core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/NoOpMetricCollector.java

@@ -15,11 +15,15 @@
 
 package software.amazon.awssdk.metrics;
 
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 
 /**
  * A metric collector that doesn't do anything.
+ *
+ * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
  */
+@SdkPreviewApi
 @SdkPublicApi
 public final class NoOpMetricCollector implements MetricCollector {
     private static final NoOpMetricCollector INSTANCE = new NoOpMetricCollector();

core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/SdkMetric.java

@@ -16,14 +16,18 @@
 package software.amazon.awssdk.metrics;
 
 import java.util.Set;
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.metrics.internal.DefaultSdkMetric;
 
 /**
  * A specific SDK metric.
  *
  * @param <T> The type for values of this metric.
+ *
+ * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
  */
+@SdkPreviewApi
 @SdkPublicApi
 public interface SdkMetric<T> {
 

core/metrics-spi/src/main/java/software/amazon/awssdk/metrics/package-info.java

@@ -0,0 +1,19 @@
+/*
+ * 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.
+ */
+
+@SdkPreviewApi
+package software.amazon.awssdk.metrics;
+
+import software.amazon.awssdk.annotations.SdkPreviewApi;

core/sdk-core/src/main/java/software/amazon/awssdk/core/RequestOverrideConfiguration.java

@@ -26,6 +26,7 @@
 import java.util.TreeMap;
 import java.util.function.Consumer;
 import software.amazon.awssdk.annotations.Immutable;
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.core.signer.Signer;
 import software.amazon.awssdk.metrics.MetricPublisher;
@@ -356,13 +357,26 @@ default B putRawQueryParameter(String name, String value) {
          * Sets the metric publishers for publishing the metrics collected for this request. This list supersedes
          * the metric publisher set on the client.
          *
+         * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
+         *
          * @param metricPublisher The list metric publisher for this request.
          * @return This object for method chaining.
          */
+        @SdkPreviewApi
         B metricPublishers(List<MetricPublisher> metricPublisher);
 
+        /**
+         * Add a metric publisher to the existing list of previously set publishers to be used for publishing metrics
+         * for this request.
+         *
+         * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
+         *
+         * @param metricPublisher The metric publisher to add.
+         */
+        @SdkPreviewApi
         B addMetricPublisher(MetricPublisher metricPublisher);
 
+        @SdkPreviewApi
         List<MetricPublisher> metricPublishers();
 
         /**

core/sdk-core/src/main/java/software/amazon/awssdk/core/client/config/ClientOverrideConfiguration.java

@@ -24,6 +24,7 @@
 import java.util.Optional;
 import java.util.TreeMap;
 import java.util.function.Consumer;
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.core.interceptor.ExecutionInterceptor;
 import software.amazon.awssdk.core.retry.RetryMode;
@@ -421,11 +422,29 @@ default Builder retryPolicy(RetryMode retryMode) {
 
         String defaultProfileName();
 
-
+        /**
+         * Set the Metric publishers to be use to publish metrics for this client. This overwrites the current list of
+         * metric publishers set on the builder.
+         *
+         * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
+         *
+         * @param metricPublishers The metric publishers.
+         */
+        @SdkPreviewApi
         Builder metricPublishers(List<MetricPublisher> metricPublishers);
 
+        /**
+         * Add a metric publisher to the existing list of previously set publishers to be used for publishing metrics
+         * for this client.
+         *
+         * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
+         *
+         * @param metricPublisher The metric publisher to add.
+         */
+        @SdkPreviewApi
         Builder addMetricPublisher(MetricPublisher metricPublisher);
 
+        @SdkPreviewApi
         List<MetricPublisher> metricPublishers();
     }
 

core/sdk-core/src/main/java/software/amazon/awssdk/core/metrics/CoreMetric.java

@@ -16,12 +16,17 @@
 package software.amazon.awssdk.core.metrics;
 
 import java.time.Duration;
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.core.retry.RetryPolicy;
 import software.amazon.awssdk.metrics.MetricCategory;
 import software.amazon.awssdk.metrics.MetricLevel;
 import software.amazon.awssdk.metrics.SdkMetric;
 
+/**
+ * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
+ */
+@SdkPreviewApi
 @SdkPublicApi
 public final class CoreMetric {
     /**

http-client-spi/src/main/java/software/amazon/awssdk/http/Http2Metric.java

@@ -15,6 +15,7 @@
 
 package software.amazon.awssdk.http;
 
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.metrics.MetricCategory;
 import software.amazon.awssdk.metrics.MetricLevel;
@@ -23,7 +24,10 @@
 /**
  * Metrics collected by HTTP clients for HTTP/2 operations. See {@link HttpMetric} for metrics that are available on both HTTP/1
  * and HTTP/2 operations.
+ *
+ * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
  */
+@SdkPreviewApi
 @SdkPublicApi
 public final class Http2Metric {
     /**

http-client-spi/src/main/java/software/amazon/awssdk/http/HttpMetric.java

@@ -15,6 +15,7 @@
 
 package software.amazon.awssdk.http;
 
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.metrics.MetricCategory;
 import software.amazon.awssdk.metrics.MetricLevel;
@@ -23,7 +24,10 @@
 /**
  * Metrics collected by HTTP clients for HTTP/1 and HTTP/2 operations. See {@link Http2Metric} for metrics that are only available
  * on HTTP/2 operations.
+ *
+ * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
  */
+@SdkPreviewApi
 @SdkPublicApi
 public final class HttpMetric {
     /**

metric-publishers/cloudwatch-metric-publisher/src/main/java/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.java

@@ -36,6 +36,7 @@
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 import software.amazon.awssdk.annotations.Immutable;
+import software.amazon.awssdk.annotations.SdkPreviewApi;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.annotations.ThreadSafe;
 import software.amazon.awssdk.core.metrics.CoreMetric;
@@ -151,7 +152,10 @@
  *
  * <p><b>Warning:</b> Make sure the {@link #close()} this publisher when it is done being used to release all resources it
  * consumes. Failure to do so will result in possible thread or file descriptor leaks.
+ *
+ * <b>NOTE:</b> This is a Preview API and is subject to change so it should not be used in production.
  */
+@SdkPreviewApi
 @ThreadSafe
 @Immutable
 @SdkPublicApi

metric-publishers/cloudwatch-metric-publisher/src/main/java/software/amazon/awssdk/metrics/publishers/cloudwatch/package-info.java

@@ -0,0 +1,19 @@
+/*
+ * 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.
+ */
+
+@SdkPreviewApi
+package software.amazon.awssdk.metrics.publishers.cloudwatch;
+
+import software.amazon.awssdk.annotations.SdkPreviewApi;