Skip to content

Commit 5af6d87

Browse files
dagnirdagnir
authored
Merge pull request #1859 from dagnir/spi-impl
Add default impls of SPI classes
2 parents 03fa2bb + faaba40 commit 5af6d87

18 files changed

+1155
-1
lines changed

‎core/metrics-spi/pom.xml

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<parent>
6+
<artifactId>core</artifactId>
7+
<groupId>software.amazon.awssdk</groupId>
8+
<version>2.13.23-SNAPSHOT</version>
9+
</parent>
10+
<modelVersion>4.0.0</modelVersion>
11+
12+
<artifactId>metrics-spi</artifactId>
13+
<name>AWS Java SDK :: Metrics SPI</name>
14+
<description> This is the base module for SDK metrics feature. It contains the interfaces used for metrics feature
15+
that are used by other modules in the library.
16+
</description>
17+
18+
<dependencies>
19+
<dependency>
20+
<groupId>software.amazon.awssdk</groupId>
21+
<artifactId>annotations</artifactId>
22+
<version>${awsjavasdk.version}</version>
23+
</dependency>
24+
<dependency>
25+
<groupId>software.amazon.awssdk</groupId>
26+
<artifactId>utils</artifactId>
27+
<version>${awsjavasdk.version}</version>
28+
</dependency>
29+
<dependency>
30+
<groupId>software.amazon.awssdk</groupId>
31+
<artifactId>test-utils</artifactId>
32+
<version>${awsjavasdk.version}</version>
33+
<scope>test</scope>
34+
</dependency>
35+
<dependency>
36+
<groupId>junit</groupId>
37+
<artifactId>junit</artifactId>
38+
<scope>test</scope>
39+
</dependency>
40+
<dependency>
41+
<groupId>com.github.tomakehurst</groupId>
42+
<artifactId>wiremock</artifactId>
43+
<scope>test</scope>
44+
</dependency>
45+
<dependency>
46+
<groupId>org.assertj</groupId>
47+
<artifactId>assertj-core</artifactId>
48+
<scope>test</scope>
49+
</dependency>
50+
<dependency>
51+
<groupId>org.mockito</groupId>
52+
<artifactId>mockito-core</artifactId>
53+
<scope>test</scope>
54+
</dependency>
55+
</dependencies>
56+
57+
58+
<build>
59+
<plugins>
60+
<plugin>
61+
<groupId>org.apache.maven.plugins</groupId>
62+
<artifactId>maven-jar-plugin</artifactId>
63+
<configuration>
64+
<archive>
65+
<manifestEntries>
66+
<Automatic-Module-Name>software.amazon.awssdk.metrics</Automatic-Module-Name>
67+
</manifestEntries>
68+
</archive>
69+
</configuration>
70+
</plugin>
71+
<plugin>
72+
<groupId>org.apache.maven.plugins</groupId>
73+
<artifactId>maven-compiler-plugin</artifactId>
74+
<configuration>
75+
<source>1.8</source>
76+
<target>1.8</target>
77+
</configuration>
78+
</plugin>
79+
</plugins>
80+
</build>
81+
</project>

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

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
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.metrics;
17+
18+
import software.amazon.awssdk.annotations.SdkPublicApi;
19+
20+
/**
21+
* A enum class representing the different types of metric categories in the SDK.
22+
* <p>
23+
* A metric can be tagged with multiple categories. Clients can enable/disable metric collection
24+
* at a {@link MetricCategory} level.
25+
*/
26+
@SdkPublicApi
27+
public enum MetricCategory {
28+
29+
/**
30+
* All metrics defined by the SDK are classified under this category at a minimum. If the metrics feature is enabled
31+
* but the category to collect is not, only metrics that are classified under this category are collected by the SDK
32+
*/
33+
DEFAULT("Default"),
34+
35+
/**
36+
* Metrics collected at the http client level are classified under this category.
37+
*/
38+
HTTP_CLIENT("HttpClient"),
39+
40+
/**
41+
* Metrics specific to streaming, eventStream APIs are classified under this category.
42+
*/
43+
STREAMING("Streaming"),
44+
45+
/**
46+
* This is an umbrella category (provided for convenience) that records metrics belonging to every category
47+
* defined in this enum. Clients who wish to collect lot of SDK metrics data should use this.
48+
* <p>
49+
* Note: Enabling this option is verbose and can be expensive based on the platform the metrics are uploaded to.
50+
* Please make sure you need all this data before using this category.
51+
*/
52+
ALL("All")
53+
54+
;
55+
56+
private final String value;
57+
58+
MetricCategory(String value) {
59+
this.value = value;
60+
}
61+
62+
public String getValue() {
63+
return value;
64+
}
65+
66+
/**
67+
* Create a {@link MetricCategory} from the given String value. This method is case insensitive.
68+
*
69+
* @param value the value to create the {@link MetricCategory} from
70+
* @return A {@link MetricCategory} if the given {@link #value} matches one of the enum values.
71+
* Otherwise throws {@link IllegalArgumentException}
72+
*/
73+
public static MetricCategory fromString(String value) {
74+
for (MetricCategory mc : MetricCategory.values()) {
75+
if (mc.value.equalsIgnoreCase(value)) {
76+
return mc;
77+
}
78+
}
79+
80+
throw new IllegalArgumentException("MetricCategory cannot be created from value: " + value);
81+
}
82+
}

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

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
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.metrics;
17+
18+
import java.util.Collection;
19+
import java.util.List;
20+
import software.amazon.awssdk.annotations.SdkPublicApi;
21+
22+
/**
23+
* An immutable collection of metrics.
24+
*/
25+
@SdkPublicApi
26+
public interface MetricCollection extends Iterable<MetricRecord<?>> {
27+
/**
28+
* @return The name of this metric collection.
29+
*/
30+
String name();
31+
32+
/**
33+
* Return all the values of the given metric.
34+
*
35+
* @param metric The metric.
36+
* @param <T> The type of the value.
37+
* @return All of the values of this metric.
38+
*/
39+
<T> List<T> metricValues(SdkMetric<T> metric);
40+
41+
/**
42+
* @return The child metric collections.
43+
*/
44+
Collection<MetricCollection> children();
45+
}

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

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
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.metrics;
17+
18+
import software.amazon.awssdk.annotations.NotThreadSafe;
19+
import software.amazon.awssdk.annotations.SdkPublicApi;
20+
import software.amazon.awssdk.metrics.internal.DefaultMetricCollector;
21+
22+
/**
23+
* Used to collect metrics reported by the SDK.
24+
*/
25+
@NotThreadSafe
26+
@SdkPublicApi
27+
public interface MetricCollector {
28+
/**
29+
* @return The name of this collector.
30+
*/
31+
String name();
32+
33+
/**
34+
* Report a metric.
35+
*/
36+
<T> void reportMetric(SdkMetric<T> metric, T data);
37+
38+
/**
39+
* Create a child of this metric collector.
40+
*
41+
* @param name The name of the child collector.
42+
* @return The child collector.
43+
*/
44+
MetricCollector createChild(String name);
45+
46+
/**
47+
* Return the collected metrics.
48+
* <p>
49+
* Calling {@code collect()} prevents further invocations of {@link #reportMetric(SdkMetric, Object)}.
50+
* @return The collected metrics.
51+
*/
52+
MetricCollection collect();
53+
54+
static MetricCollector create(String name) {
55+
return DefaultMetricCollector.create(name);
56+
}
57+
}

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

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
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.metrics;
17+
18+
import software.amazon.awssdk.annotations.SdkPublicApi;
19+
import software.amazon.awssdk.annotations.ThreadSafe;
20+
import software.amazon.awssdk.metrics.MetricCollection;
21+
import software.amazon.awssdk.utils.SdkAutoCloseable;
22+
23+
/**
24+
* Interface to report and publish the collected SDK metric events to external
25+
* sources.
26+
* <p>
27+
* Conceptually, a publisher receives a stream of {@link MetricCollection} objects
28+
* overs its lifetime through its {@link #publish(MetricCollection)} )} method.
29+
* Implementations are then free further aggregate these events into sets of
30+
* metrics that are then published to some external system for further use.
31+
* As long as a publisher is not closed, then it can receive {@code
32+
* MetricCollection} objects at any time. In addition, as the SDK makes use of
33+
* multithreading, it's possible that the publisher is shared concurrently by
34+
* multiple threads, and necessitates that all implementations are threadsafe.
35+
* <p>
36+
* The SDK may invoke methods on the interface from multiple threads
37+
* concurrently so implementations must be threadsafe.
38+
*/
39+
@ThreadSafe
40+
@SdkPublicApi
41+
public interface MetricPublisher extends SdkAutoCloseable {
42+
/**
43+
* Notify the publisher of new metric data. After this call returns, the
44+
* caller can safely discard the given {@code metricCollection} instance if it
45+
* no longer needs it. Implementations are strongly encouraged to complete
46+
* any further aggregation and publishing of metrics in an asynchronous manner to
47+
* avoid blocking the calling thread.
48+
* <p>
49+
* With the exception of a {@code null} {@code metricCollection}, all
50+
* invocations of this method must return normally. This
51+
* is to ensure that callers of the publisher can safely assume that even
52+
* in situations where an error happens during publishing that it will not
53+
* interrupt the calling thread.
54+
*
55+
* @param metricCollection The collection of metrics.
56+
* @throws IllegalArgumentException If {@code metricCollection} is {@code null}.
57+
*/
58+
void publish(MetricCollection metricCollection);
59+
60+
/**
61+
* {@inheritDoc}
62+
* <p>
63+
* <b>Important:</b> Implementations must block the calling thread until all
64+
* pending metrics are published and any resources acquired have been freed.
65+
*/
66+
@Override
67+
void close();
68+
}

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
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.metrics;
17+
18+
import software.amazon.awssdk.annotations.SdkPublicApi;
19+
20+
/**
21+
* A container associating a metric and its value.
22+
*/
23+
@SdkPublicApi
24+
public interface MetricRecord<T> {
25+
/**
26+
* @return The metric.
27+
*/
28+
SdkMetric<T> metric();
29+
30+
/**
31+
* @return The value of this metric.
32+
*/
33+
T value();
34+
}

0 commit comments

Comments
 (0)