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.http;
17 
18 import java.time.Duration;
19 import software.amazon.awssdk.annotations.SdkPublicApi;
20 import software.amazon.awssdk.metrics.MetricCategory;
21 import software.amazon.awssdk.metrics.MetricLevel;
22 import software.amazon.awssdk.metrics.SdkMetric;
23 
24 /**
25  * Metrics collected by HTTP clients for HTTP/1 and HTTP/2 operations. See {@link Http2Metric} for metrics that are only available
26  * on HTTP/2 operations.
27  */
28 @SdkPublicApi
29 public final class HttpMetric {
30     /**
31      * The name of the HTTP client.
32      */
33     public static final SdkMetric<String> HTTP_CLIENT_NAME =
34         metric("HttpClientName", String.class, MetricLevel.INFO);
35 
36     /**
37      * The maximum number of concurrent requests that is supported by the HTTP client.
38      *
39      * <p>For HTTP/1 operations, this is equal to the maximum number of TCP connections that can be be pooled by the HTTP client.
40      * For HTTP/2 operations, this is equal to the maximum number of streams that can be pooled by the HTTP client.
41      *
42      * <p>Note: Depending on the HTTP client, this is either a value for all endpoints served by the HTTP client, or a value
43      * that applies only to the specific endpoint/host used in the request. For 'apache-http-client', this value is
44      * for the entire HTTP client. For 'netty-nio-client', this value is per-endpoint. In all cases, this value is scoped to an
45      * individual HTTP client instance, and does not include concurrency that may be available in other HTTP clients running
46      * within the same JVM.
47      */
48     public static final SdkMetric<Integer> MAX_CONCURRENCY =
49         metric("MaxConcurrency", Integer.class, MetricLevel.INFO);
50 
51     /**
52      * The number of additional concurrent requests that can be supported by the HTTP client without needing to establish
53      * additional connections to the target server.
54      *
55      * <p>For HTTP/1 operations, this is equal to the number of TCP connections that have been established with the service,
56      * but are currently idle/unused. For HTTP/2 operations, this is equal to the number of streams that are currently
57      * idle/unused.
58      *
59      * <p>Note: Depending on the HTTP client, this is either a value for all endpoints served by the HTTP client, or a value
60      * that applies only to the specific endpoint/host used in the request. For 'apache-http-client', this value is
61      * for the entire HTTP client. For 'netty-nio-client', this value is per-endpoint. In all cases, this value is scoped to an
62      * individual HTTP client instance, and does not include concurrency that may be available in other HTTP clients running
63      * within the same JVM.
64      */
65     public static final SdkMetric<Integer> AVAILABLE_CONCURRENCY =
66         metric("AvailableConcurrency", Integer.class, MetricLevel.INFO);
67 
68     /**
69      * The number of requests that are currently being executed by the HTTP client.
70      *
71      * <p>For HTTP/1 operations, this is equal to the number of TCP connections currently in active communication with the service
72      * (excluding idle connections). For HTTP/2 operations, this is equal to the number of HTTP streams currently in active
73      * communication with the service (excluding idle stream capacity).
74      *
75      * <p>Note: Depending on the HTTP client, this is either a value for all endpoints served by the HTTP client, or a value
76      * that applies only to the specific endpoint/host used in the request. For 'apache-http-client', this value is
77      * for the entire HTTP client. For 'netty-nio-client', this value is per-endpoint. In all cases, this value is scoped to an
78      * individual HTTP client instance, and does not include concurrency that may be available in other HTTP clients running
79      * within the same JVM.
80      */
81     public static final SdkMetric<Integer> LEASED_CONCURRENCY =
82         metric("LeasedConcurrency", Integer.class, MetricLevel.INFO);
83 
84     /**
85      * The number of requests that are awaiting concurrency to be made available from the HTTP client.
86      *
87      * <p>For HTTP/1 operations, this is equal to the number of requests currently blocked, waiting for a TCP connection to be
88      * established or returned from the connection pool. For HTTP/2 operations, this is equal to the number of requests currently
89      * blocked, waiting for a new stream (and possibly a new HTTP/2 connection) from the connection pool.
90      *
91      * <p>Note: Depending on the HTTP client, this is either a value for all endpoints served by the HTTP client, or a value
92      * that applies only to the specific endpoint/host used in the request. For 'apache-http-client', this value is
93      * for the entire HTTP client. For 'netty-nio-client', this value is per-endpoint. In all cases, this value is scoped to an
94      * individual HTTP client instance, and does not include concurrency that may be available in other HTTP clients running
95      * within the same JVM.
96      */
97     public static final SdkMetric<Integer> PENDING_CONCURRENCY_ACQUIRES =
98         metric("PendingConcurrencyAcquires", Integer.class, MetricLevel.INFO);
99 
100     /**
101      * The status code of the HTTP response.
102      *
103      * <p>
104      * This is reported by the SDK core, and should not be reported by an individual HTTP client implementation.
105      */
106     public static final SdkMetric<Integer> HTTP_STATUS_CODE =
107         metric("HttpStatusCode", Integer.class, MetricLevel.TRACE);
108 
109     /**
110      * The time taken to acquire a channel from the connection pool.
111      *
112      * <p>For HTTP/1 operations, a channel is equivalent to a TCP connection. For HTTP/2 operations, a channel is equivalent to
113      * an HTTP/2 stream channel. For both protocols, the time to acquire a new channel may include the following:
114      * <ol>
115      *     <li>Awaiting a concurrency permit, as restricted by the client's max concurrency configuration.</li>
116      *     <li>The time to establish a new connection, depending on whether an existing connection is available in the pool or
117      *     not.</li>
118      *     <li>The time taken to perform a TLS handshake/negotiation, if TLS is enabled.</li>
119      * </ol>
120      */
121     public static final SdkMetric<Duration> CONCURRENCY_ACQUIRE_DURATION =
122         metric("ConcurrencyAcquireDuration", Duration.class, MetricLevel.INFO);
123 
HttpMetric()124     private HttpMetric() {
125     }
126 
metric(String name, Class<T> clzz, MetricLevel level)127     private static <T> SdkMetric<T> metric(String name, Class<T> clzz, MetricLevel level) {
128         return SdkMetric.create(name, clzz, level, MetricCategory.CORE, MetricCategory.HTTP_CLIENT);
129     }
130 }
131