Metrics: Add interfaces and initial implementations

core/aws-core/src/main/java/software/amazon/awssdk/awscore/client/handler/AwsClientHandlerUtils.java

@@ -40,6 +40,7 @@
 import software.amazon.awssdk.core.interceptor.ExecutionAttributes;
 import software.amazon.awssdk.core.interceptor.ExecutionInterceptorChain;
 import software.amazon.awssdk.core.interceptor.InterceptorContext;
+import software.amazon.awssdk.core.interceptor.MetricExecutionAttribute;
 import software.amazon.awssdk.core.interceptor.SdkExecutionAttribute;
 import software.amazon.awssdk.core.interceptor.SdkInternalExecutionAttribute;
 import software.amazon.awssdk.core.signer.Signer;
@@ -84,6 +85,10 @@ static <InputT extends SdkRequest, OutputT extends SdkResponse> ExecutionContext
             .putAttribute(SdkExecutionAttribute.CLIENT_TYPE, clientConfig.option(SdkClientOption.CLIENT_TYPE))
             .putAttribute(SdkExecutionAttribute.SERVICE_NAME, clientConfig.option(SdkClientOption.SERVICE_NAME))
             .putAttribute(SdkExecutionAttribute.OPERATION_NAME, executionParams.getOperationName())
+            .putAttribute(MetricExecutionAttribute.METRIC_CONFIGURATION_PROVIDER,
+                          clientConfig.option(SdkClientOption.METRIC_CONFIGURATION_PROVIDER))
+            .putAttribute(MetricExecutionAttribute.METRIC_PUBLISHER_CONFIGURATION,
+                          clientConfig.option(SdkClientOption.METRIC_PUBLISHER_CONFIGURATION))
             .putAttribute(SdkExecutionAttribute.ENDPOINT_OVERRIDDEN,
                           clientConfig.option(SdkClientOption.ENDPOINT_OVERRIDDEN));
 

core/metrics-spi/pom.xml

@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <artifactId>core</artifactId>
+        <groupId>software.amazon.awssdk</groupId>
+        <version>2.10.46-SNAPSHOT</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>metrics-spi</artifactId>
+    <name>AWS Java SDK :: Metrics SPI</name>
+    <description> This is the base module for SDK metrics feature. It contains the interfaces used for metrics feature
+        that are used by other modules in the library.
+    </description>
+
+    <dependencies>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>annotations</artifactId>
+            <version>${awsjavasdk.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>utils</artifactId>
+            <version>${awsjavasdk.version}</version>
+        </dependency>
+
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>test-utils</artifactId>
+            <version>${awsjavasdk.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.github.tomakehurst</groupId>
+            <artifactId>wiremock</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-jar-plugin</artifactId>
+                <configuration>
+                    <archive>
+                        <manifestEntries>
+                            <Automatic-Module-Name>software.amazon.awssdk.metrics</Automatic-Module-Name>
+                        </manifestEntries>
+                    </archive>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <source>1.8</source>
+                    <target>1.8</target>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>

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

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2010-2020 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.metrics.metrics.SdkDefaultMetric;
+
+/**
+ * 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.
+ *
+ * @see SdkDefaultMetric
+ */
+@SdkPublicApi
+public enum MetricCategory {
+
+    /**
+     * All metrics defined by the SDK are classified under this category at a minimum. If the metrics feature is enabled
+     * but the category to collect is not, only metrics that are classified under this category are collected by the SDK
+     */
+    DEFAULT("default"),
+
+    /**
+     * Metrics collected at the http client level are classified under this category.
+     */
+    HTTP_CLIENT("httpclient"),
+
+    /**
+     * Metrics specific to streaming, eventStream APIs are classified under this category.
+     */
+    STREAMING("streaming"),
+
+    /**
+     * 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.
+     * <p>
+     * Note: Enabling this option 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);
+    }
+}

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

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2010-2020 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.internal;
+
+import software.amazon.awssdk.annotations.SdkInternalApi;
+import software.amazon.awssdk.metrics.MetricCategory;
+import software.amazon.awssdk.utils.SystemSetting;
+
+/**
+ * System properties to configure metrics options in the SDK.
+ */
+@SdkInternalApi
+public enum MetricSystemSetting implements SystemSetting {
+
+    /**
+     * Enable the Java SDK Metrics by setting this property. Metrics feature is disabled if this feature is not specified or
+     * specified to anything other than "true"
+     */
+    AWS_JAVA_SDK_METRICS_ENABLED("aws.javasdk2x.metrics.enabled", null),
+
+    /**
+     * Specify comma separated {@link MetricCategory} values to enable the categories for metrics collection.
+     * Only metrics belonging to these categories are collected by the SDK.
+     *
+     * <p>
+     * This value is defaulted to {@link MetricCategory#DEFAULT}. If this property is not set but metrics are enabled,
+     * then metrics belonging to {@link MetricCategory#DEFAULT} category are collected.
+     * </p>
+     */
+    AWS_JAVA_SDK_METRICS_CATEGORY("aws.javasdk2x.metrics.category", "Default")
+
+    ;
+
+    private final String systemProperty;
+    private final String defaultValue;
+
+    MetricSystemSetting(String systemProperty, String defaultValue) {
+        this.systemProperty = systemProperty;
+        this.defaultValue = defaultValue;
+    }
+
+    @Override
+    public String property() {
+        return systemProperty;
+    }
+
+    @Override
+    public String environmentVariable() {
+        return name();
+    }
+
+    @Override
+    public String defaultValue() {
+        return defaultValue;
+    }
+}

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

@@ -0,0 +1,105 @@
+/*
+ * Copyright 2010-2020 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.meter;
+
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.metrics.MetricCategory;
+import software.amazon.awssdk.utils.Validate;
+
+/**
+ * A {@link Gauge} implementation that stores a constant value for a metric.
+ * The value stored cannot be changed after object creation
+ *
+ * @param <TypeT> the type of the value recorded in the Gauge
+ */
+@SdkPublicApi
+public final class ConstantGauge<TypeT> implements Gauge<TypeT> {
+
+    private final TypeT value;
+    private final Set<MetricCategory> categories;
+
+    private ConstantGauge(Builder<TypeT> builder) {
+        this.value = Validate.notNull(builder.value, "Value cannot be null");
+        this.categories = Collections.unmodifiableSet(builder.categories);
+    }
+
+    @Override
+    public TypeT value() {
+        return value;
+    }
+
+    @Override
+    public Set<MetricCategory> categories() {
+        return categories;
+    }
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * @param value the value to store in the guage
+     * @param <T> type of the value
+     * @return An instance of {@link ConstantGauge} with the given {@link #value} stored in the gauge.
+     */
+    public static <T> ConstantGauge<T> create(T value) {
+        return builder().value(value).build();
+    }
+
+    public static final class Builder<BuilderT> {
+        private BuilderT value;
+        private final Set<MetricCategory> categories = new HashSet<>();
+
+        private Builder() {
+        }
+
+        /**
+         * @param value the value to store in the gauge
+         * @return This object for method chaining
+         */
+        public Builder<BuilderT> value(BuilderT value) {
+            this.value = value;
+            return this;
+        }
+
+        /**
+         * Register the given categories in this metric
+         * @param categories the set of {@link MetricCategory} this metric belongs to
+         * @return This object for method chaining
+         */
+        public Builder<BuilderT> categories(Set<MetricCategory> categories) {
+            this.categories.addAll(categories);
+            return this;
+        }
+
+        /**
+         * Register the given {@link MetricCategory} in this metric
+         * @param category the {@link MetricCategory} to tag the metric with
+         * @return This object for method chaining
+         */
+        public Builder<BuilderT> addCategory(MetricCategory category) {
+            this.categories.add(category);
+            return this;
+        }
+
+        public ConstantGauge<BuilderT> build() {
+            return new ConstantGauge(this);
+        }
+    }
+}