使用来自 SDK 的指标 AWS SDK for Java - AWS SDK for Java 2.x

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

使用来自 SDK 的指标 AWS SDK for Java

使用 AWS SDK for Java 2.x,您可以收集有关应用程序中服务客户端的指标,分析其中的输出 Amazon CloudWatch,然后对其采取行动。

默认情况下,SDK 中的指标收集处于禁用状态。本主题可帮助您启用和配置指标收集。

先决条件

必须先完成以下步骤,然后才能启用并使用指标。

  • 完成设置 AWS SDK for Java 2.x中的步骤。

  • 将项目依赖项(例如,在您的 pom.xmlbuild.gradle 文件中)配置为使用 AWS SDK for Java版本 2.14.0 或更高版本。

    要启用向发布指标 CloudWatch,还需要在项目的依赖项中包含带有版本2.14.0号或更高版本号的 cloudwatch-metric-publisher ArtifactID。

    例如:

    <project> <dependencyManagement> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>bom</artifactId> <version>2.14.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>cloudwatch-metric-publisher</artifactId> <version>2.14.0</version> </dependency> </dependencies> </project>
  • 为指标发布者使用的 IAM 身份启用cloudwatch:PutMetricData权限,以允许 Java SDK 编写指标。

如何启用指标收集

您可以在应用程序中为服务客户端或单个请求启用指标。

为特定请求启用指标

以下课程说明如何为请求启用 CloudWatch 指标发布器 Amazon DynamoDB。该代码段使用默认的指标发布者配置。

import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.dynamodb.model.ListTablesRequest; public class DefaultConfigForRequest { // Use one MetricPublisher for your application. It can be used with requests or service clients. static MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); public static void main(String[] args) { DynamoDbClient ddb = DynamoDbClient.create(); // Publish metrics the for ListTables operation. ddb.listTables(ListTablesRequest.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build()); // Perform more work in your application. // A MetricsPublisher has its own lifecycle independent of any service client or request that uses it. // If you no longer need the publisher, close it to free up resources. metricsPub.close(); // All metrics stored in memory are flushed to CloudWatch. // Perform more work with the DynamoDbClient instance without publishing metrics. // Close the service client when you no longer need it. ddb.close(); } }
重要

当服务客户端不再使用时,请确保您的应用程序在MetricPublisher实例close上调用。否则,可能会导致线程或文件描述符泄漏。

为特定服务客户端启用摘要指标

以下代码片段显示了如何为服务客户端启用具有默认设置的 CloudWatch 指标发布者。

MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build();

自定义指标发布者

以下课程演示如何为特定服务客户端的指标发布者设置自定义配置。自定义设置包括加载特定的配置文件、指定指标发布者向其发送请求的 AWS 区域,以及自定义发布者向其发送指标的频率。 CloudWatch

import software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider; import software.amazon.awssdk.core.metrics.CoreMetric; import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.cloudwatch.CloudWatchAsyncClient; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import java.time.Duration; public class CustomConfigForDDBClient { // Use one MetricPublisher for your application. It can be used with requests or service clients. static MetricPublisher metricsPub = CloudWatchMetricPublisher.builder() .cloudWatchClient(CloudWatchAsyncClient.builder() .region(Region.US_WEST_2) .credentialsProvider(ProfileCredentialsProvider.create("cloudwatch")) .build()) .uploadFrequency(Duration.ofMinutes(5)) .maximumCallsPerUpload(100) .namespace("ExampleSDKV2Metrics") .detailedMetrics(CoreMetric.API_CALL_DURATION) .build(); public static void main(String[] args) { DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); // Publish metrics for DynamoDB operations. ddb.listTables(); ddb.describeEndpoints(); ddb.describeLimits(); // Perform more work in your application. // A MetricsPublisher has its own lifecycle independent of any service client or request that uses it. // If you no longer need the publisher, close it to free up resources. metricsPub.close(); // All metrics stored in memory are flushed to CloudWatch. // Perform more work with the DynamoDbClient instance without publishing metrics. // Close the service client when you no longer need it. ddb.close(); } }

上一个片段中显示的自定义设置具有以下效果。

  • cloudWatchClient方法允许您自定义用于发送指标的 CloudWatch 客户端。在此示例中,我们使用了与客户端发送指标的默认区域 us-east-1 不同的区域。我们还使用不同的命名配置文件 cloudwatch,其凭据将用于对请求进行 CloudWatch身份验证。这些证书必须具有权限cloudwatch:PutMetricData

  • uploadFrequency方法允许您指定指标发布者上传指标的频率。 CloudWatch默认值为每分钟一次。

  • maximumCallsPerUpload方法限制每次上传的调用次数。默认为无限制。

  • 默认情况下,适用于 Java 的 SDK 2.x 会在命名空间AwsSdk/JavaSdk2下发布指标。您可以使用该namespace方法来指定不同的值。

  • 默认情况下,SDK 会发布摘要指标。摘要指标包括平均值、最小值、最大值、总和和和样本数。通过在detailedMetrics方法中指定一个或多个 SDK 指标,SDK 会为每个指标发布更多数据。这些附加数据支持百分位数统计信息,例如 p90 和 p99,供您查询。 CloudWatch详细指标对于延迟指标特别有用APICallDuration,例如衡量 SDK 客户端请求的 end-to-end 延迟。您可以使用CoreMetric类的字段来指定其他常用 SDK 指标。

指标何时可用?

指标通常在 SDK for Java 发出它们后的 5-10 分钟内可用。要获得准确性和 up-to-date 指标,请在从 Java 应用程序发出指标至少 10 分钟后查看 Cloudwatch。

收集哪些信息?

指标收集包括以下内容:

  • API 请求的数量,包括请求成功还是失败

  • 有关您在 API 请求中调用的 AWS 服务的信息,包括返回的异常

  • 封送、签名和 HTTP 请求等各种操作的用时

  • HTTP 客户端指标,例如打开的连接数、待处理的请求数以及所使用的 HTTP 客户端的名称

注意

可用指标因 HTTP 客户端而异。

有关完整列表,请参阅服务客户端指标

我该如何使用这些信息?

您可以使用 SDK 收集的指标来监控应用程序中的服务客户端。您可以查看总体使用趋势,识别异常情况,查看返回的服务客户端异常,或者深入了解特定问题。您还可以使用 Amazon CloudWatch创建警报,以便在应用程序达到您定义的条件时立即通知您。

有关更多信息,请参阅Amazon CloudWatch 用户指南中的使用 Amazon CloudWatch 指标和使用 Amazon CloudWatch 警报

主题