software.amazon.awssdk.http.HttpMetric Maven / Gradle / Ivy

Go to download
/*
 * 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.http;

import java.time.Duration;
import software.amazon.awssdk.annotations.SdkPublicApi;
import software.amazon.awssdk.metrics.MetricCategory;
import software.amazon.awssdk.metrics.MetricLevel;
import software.amazon.awssdk.metrics.SdkMetric;

/**
 * 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.
 */
@SdkPublicApi
public final class HttpMetric {
    /**
     * The name of the HTTP client.
     */
    public static final SdkMetric HTTP_CLIENT_NAME =
        metric("HttpClientName", String.class, MetricLevel.INFO);

    /**
     * The maximum number of concurrent requests that is supported by the HTTP client.
     *
     * For HTTP/1 operations, this is equal to the maximum number of TCP connections that can be be pooled by the HTTP client.
     * For HTTP/2 operations, this is equal to the maximum number of streams that can be pooled by the HTTP client.
     *
     * 
Note: Depending on the HTTP client, this is either a value for all endpoints served by the HTTP client, or a value
     * that applies only to the specific endpoint/host used in the request. For 'apache-http-client', this value is
     * for the entire HTTP client. For 'netty-nio-client', this value is per-endpoint. In all cases, this value is scoped to an
     * individual HTTP client instance, and does not include concurrency that may be available in other HTTP clients running
     * within the same JVM.
     */
    public static final SdkMetric MAX_CONCURRENCY =
        metric("MaxConcurrency", Integer.class, MetricLevel.INFO);

    /**
     * The number of additional concurrent requests that can be supported by the HTTP client without needing to establish
     * additional connections to the target server.
     *
     * 
For HTTP/1 operations, this is equal to the number of TCP connections that have been established with the service,
     * but are currently idle/unused. For HTTP/2 operations, this is equal to the number of streams that are currently
     * idle/unused.
     *
     * 
Note: Depending on the HTTP client, this is either a value for all endpoints served by the HTTP client, or a value
     * that applies only to the specific endpoint/host used in the request. For 'apache-http-client', this value is
     * for the entire HTTP client. For 'netty-nio-client', this value is per-endpoint. In all cases, this value is scoped to an
     * individual HTTP client instance, and does not include concurrency that may be available in other HTTP clients running
     * within the same JVM.
     */
    public static final SdkMetric AVAILABLE_CONCURRENCY =
        metric("AvailableConcurrency", Integer.class, MetricLevel.INFO);

    /**
     * The number of requests that are currently being executed by the HTTP client.
     *
     * 
For HTTP/1 operations, this is equal to the number of TCP connections currently in active communication with the service
     * (excluding idle connections). For HTTP/2 operations, this is equal to the number of HTTP streams currently in active
     * communication with the service (excluding idle stream capacity).
     *
     * 
Note: Depending on the HTTP client, this is either a value for all endpoints served by the HTTP client, or a value
     * that applies only to the specific endpoint/host used in the request. For 'apache-http-client', this value is
     * for the entire HTTP client. For 'netty-nio-client', this value is per-endpoint. In all cases, this value is scoped to an
     * individual HTTP client instance, and does not include concurrency that may be available in other HTTP clients running
     * within the same JVM.
     */
    public static final SdkMetric LEASED_CONCURRENCY =
        metric("LeasedConcurrency", Integer.class, MetricLevel.INFO);

    /**
     * The number of requests that are awaiting concurrency to be made available from the HTTP client.
     *
     * 
For HTTP/1 operations, this is equal to the number of requests currently blocked, waiting for a TCP connection to be
     * established or returned from the connection pool. For HTTP/2 operations, this is equal to the number of requests currently
     * blocked, waiting for a new stream (and possibly a new HTTP/2 connection) from the connection pool.
     *
     * 
Note: Depending on the HTTP client, this is either a value for all endpoints served by the HTTP client, or a value
     * that applies only to the specific endpoint/host used in the request. For 'apache-http-client', this value is
     * for the entire HTTP client. For 'netty-nio-client', this value is per-endpoint. In all cases, this value is scoped to an
     * individual HTTP client instance, and does not include concurrency that may be available in other HTTP clients running
     * within the same JVM.
     */
    public static final SdkMetric PENDING_CONCURRENCY_ACQUIRES =
        metric("PendingConcurrencyAcquires", Integer.class, MetricLevel.INFO);

    /**
     * The status code of the HTTP response.
     *
     * @implSpec This is reported by the SDK core, and should not be reported by an individual HTTP client implementation.
     */
    public static final SdkMetric HTTP_STATUS_CODE =
        metric("HttpStatusCode", Integer.class, MetricLevel.TRACE);

    /**
     * The time taken to acquire a channel from the connection pool.
     *
     * 
For HTTP/1 operations, a channel is equivalent to a TCP connection. For HTTP/2 operations, a channel is equivalent to
     * an HTTP/2 stream channel. For both protocols, the time to acquire a new channel may include the following:
     * 

     *     Awaiting a concurrency permit, as restricted by the client's max concurrency configuration.
     *     The time to establish a new connection, depending on whether an existing connection is available in the pool or
     *     not.
     *     The time taken to perform a TLS handshake/negotiation, if TLS is enabled.
     * 
     */
    public static final SdkMetric CONCURRENCY_ACQUIRE_DURATION =
        metric("ConcurrencyAcquireDuration", Duration.class, MetricLevel.INFO);

    private HttpMetric() {
    }

    private static  SdkMetric metric(String name, Class clzz, MetricLevel level) {
        return SdkMetric.create(name, clzz, level, MetricCategory.CORE, MetricCategory.HTTP_CLIENT);
    }
}