本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 从中发布 SDK 指标 AWS SDK for Java 2.x 借助， AWS SDK for Java 2.x 您可以收集有关应用程序中服务客户端和请求的指标，分析 Amazon CloudWatch Logs 中的输出，然后对其采取行动。 默认情况下，SDK 中的指标收集处于禁用状态。本主题可帮助您启用和配置指标收集。 ## SDK 指标入门 要在应用程序中启用指标收集，请根据您的使用案例选择适当的 `[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)` 接口实现，并按照详细的设置说明进行操作： **对于长时间运行的应用程序：** + 使用 `[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)` + 有关完整的设置说明、代码示例和配置选项，请参阅[从长时间运行的应用程序发布 SDK 指标](metric-pub-impl-cwmp.md)。 **对于 AWS Lambda 函数：** + 使用 `[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)` + 有关完整的设置说明、依赖关系和特定于 Lambda 的配置，请参阅[发布 SDK AWS Lambda 函数指标](metric-pub-impl-emf.md)。 **对于故障排除和控制台输出：** + 使用 `[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)` + 有关本地开发和故障排除的设置说明、格式选项以及示例，请参阅[将 SDK 指标输出到控制台进行开发和调试](metric-pub-impl-logging.md)。 ## 快速实施预览 以下是针对每个使用案例启用指标的具体示例： **长时间运行的应用程序：** ``` MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); ``` **Lambda 函数：** ``` EmfMetricLoggingPublisher emfPublisher = EmfMetricLoggingPublisher.builder() .namespace("MyApp") .build(); DynamoDbClient dynamoDb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher)) .build(); ``` **开发和调试：** ``` MetricPublisher loggingPublisher = LoggingMetricPublisher.create(); S3Client s3 = S3Client.builder() .overrideConfiguration(c -> c.addMetricPublisher(loggingPublisher)) .build(); ``` ## 基于 AWS CRT 的 S3 客户端的指标限制 [基于AWS CRT 的 S3 客户端](crt-based-s3-client.md)目前不支持 SDK 指标收集。 AWS 基于 CRT 的 S3 客户端实例的构建器不提供配置指标发布者的方法。[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3CrtAsyncClientBuilder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3CrtAsyncClientBuilder.html) ## 指标何时可用？ 指标通常在 SDK for Java 发出它们后的 5-10 分钟内可用。要获得准确性和 up-to-date指标，请在从 Java 应用程序发出指标至少 10 分钟后查看 Cloudwatch。 ## 收集哪些信息？ 指标收集包括以下内容： + API 请求的数量，包括请求成功还是失败 + 有关 AWS 服务 您在 API 请求中调用的信息，包括返回的异常 + 封送、签名和 HTTP 请求等各种操作的用时 + HTTP 客户端指标，例如打开的连接数、待处理的请求数以及所使用的 HTTP 客户端的名称 **注意** 可用指标因 HTTP 客户端而异。 有关完整列表，请参阅[服务客户端指标](metrics-list.md)。 ## 我该如何使用这些信息？ 您可以使用 SDK 收集的指标来监控应用程序中的服务客户端。您可以查看总体使用趋势、识别异常情况、查看返回的服务客户端异常，或者深入了解特定问题。使用 Ama CloudWatch zon Logs，您还可以创建警报，以便在应用程序达到您定义的条件时立即通知您。 有关更多信息，请参阅《[亚马逊 CloudWatch 日志用户指南》中的 “使用亚马逊 CloudWatch 日志指标](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) [[” 和 “使用亚马逊 CloudWatch 日志](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)警报](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)”。 # 使用长时间运行的应用程序发布 SDK 指标 AWS SDK for Java 2.x 由于该`[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)`实施会汇总指标并将其定期上传到 Amazon CloudWatch ，因此其使用最适合长时间运行的应用程序。 指标发布者的默认设置旨在最大限度地减少内存使用量和 CloudWatch 成本，同时仍能为指标数据提供有用的见解。 ## 设置 先完成以下步骤，然后才能使用 `CloudWatchMetricPublisher` 来启用和使用指标。 ### 步骤 1：添加所需的依赖项 将项目依赖项（例如，在您的 `pom.xml` 或 `build.gradle` 文件中）配置为使用 适用于 Java 的 AWS SDK版本 `2.14.0` 或更高版本。 在项目的依赖项中包括 artifactId `cloudwatch-metric-publisher`，并使用版本号 `2.14.0` 或更高版本号。 例如： ``` software.amazon.awssdk bom [2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) pom import software.amazon.awssdk cloudwatch-metric-publisher ``` ### 步骤 2：配置所需的权限 为指标发布者使用的 IAM 身份启用 `cloudwatch:PutMetricData` 权限，以允许适用于 Java 的 SDK 编写指标。 ## 为特定请求启用指标 以下课程展示了如何为向 Amazon DynamoDB 发出的请求启用 CloudWatch 指标发布者。该类使用默认的指标发布者配置。 ``` 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](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)` 实例上调用 `close`。否则可能会导致线程泄漏或文件描述符泄漏。 ## 为特定服务客户端启用摘要指标 以下代码片段显示了如何为服务客户端启用具有默认设置的 CloudWatch 指标发布者。 ``` MetricPublisher metricsPub = CloudWatchMetricPublisher.create(); DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(metricsPub)) .build(); ``` ## 自定义 CloudWatch 指标发布者 以下类演示如何为特定服务客户端的指标发布者设置自定义配置。自定义设置包括加载特定的配置文件、指定指标发布者向其发送请求的 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](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/metrics/CoreMetric.html)` 类的字段来指定其他常用 SDK 指标。 **后续步骤：**如果您也在使用 Lambda 函数，请参阅[发布基于 EMF 的指标发布 AWS Lambda 函数的 SDK 指标](metric-pub-impl-emf.md)。 # 使用发布 AWS Lambda 函数的 SDK 指标 AWS SDK for Java 2.x 由于 Lambda 函数的执行时间通常为几毫秒到几分钟，而使用 `CloudWatchMetricPublisher` 发送指标存在延迟，这种延迟可能导致指标数据丢失。 `[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)`通过立即将指标写成[CloudWatch 嵌入式指标格式 (EMF)](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html) 的结构化日志条目，提供了一种更合适的方法。 `EmfMetricLoggingPublisher`适用于与 Amazon L CloudWatch ogs 内置集成的执行环境，例如 AWS Lambda 和亚马逊弹性容器服务。 ## 设置 先完成以下步骤，然后才能使用 `EmfMetricLoggingPublisher` 来启用和使用指标。 ### 步骤 1：添加所需的依赖项 将项目依赖项（例如，在您的 `pom.xml` 或 `build.gradle` 文件中）配置为使用 适用于 Java 的 AWS SDK版本 `2.30.3` 或更高版本。 在项目的依赖项中包括 artifactId `emf-metric-logging-publisher`，并使用版本号 `2.30.3` 或更高版本号。 例如： ``` software.amazon.awssdk bom [2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) pom import software.amazon.awssdk emf-metric-logging-publisher ``` ### 步骤 2：配置所需的权限 为指标发布者使用的 IAM 身份启用 `logs:PutLogEvents` 权限，以允许适用于 Java 的 SDK 编写 EMF 格式的日志。 ### 步骤 3：设置日志记录 为确保正确收集指标，请将您的日志记录配置为以 `INFO` 级别或更低级别（例如 `DEBUG`）输出到控制台。在 `log4j2.xml` 文件中： ``` ``` 有关如何设置 `log4j2.xml` 文件的更多信息，请参阅本指南中的[日志记录主题](logging-slf4j.md)。 ## 配置和使用 `EmfMetricLoggingPublisher`。 以下 Lambda 函数类先创建和配置 `EmfMetricLoggingPublisher` 实例，然后将其与 Amazon DynamoDB 服务客户端一起使用： ``` public class GameIdHandler implements RequestHandler, String> { private final EmfMetricLoggingPublisher emfPublisher; private final DynamoDbClient dynamoDb; public GameIdHandler() { // Build the publisher. this.emfPublisher = EmfMetricLoggingPublisher.builder() .namespace("namespace") .dimensions(CoreMetric.SERVICE_ID, CoreMetric.OPERATION_NAME) .build(); // Add the publisher to the client. this.dynamoDb = DynamoDbClient.builder() .overrideConfiguration(c -> c.addMetricPublisher(emfPublisher)) .region(Region.of(System.getenv("AWS_REGION"))) .build(); } @Override public String handleRequest(Map event, Context context) { Map gameItem = new HashMap<>(); gameItem.put("gameId", AttributeValue.builder().s(event.get("id")).build()); PutItemRequest putItemRequest = PutItemRequest.builder() .tableName("games") .item(gameItem) .build(); dynamoDb.putItem(putItemRequest); return "Request handled"; } } ``` 当 DynamoDB 客户端执行`putItem`该方法时，它会自动以 EMF 格式将指标发布到日志 CloudWatch 流。 ### EMF 日志事件的示例 例如，如果您将以下事件发送到 GameHandler Lambda 函数，且日志配置如前所示： ``` { "id": "23456" } ``` 函数处理事件后，您会看到两个与以下示例类似的日志事件。第二个事件中的 JSON 对象包含 DynamoDB `PutItem` 操作的 Java SDK 指标数据。 当 CloudWatch 收到 EMF 格式的日志事件时，它会自动解析结构化的 JSON 以提取指标数据。 CloudWatch 然后创建相应的指标，同时将原始日志条目存储在 CloudWatch 日志中。 ``` 2025-07-11 15:58:30 [main] INFO org.example.GameIdHandler:39 - Received map: {id=23456} 2025-07-11 15:58:34 [main] INFO software.amazon.awssdk.metrics.publishers.emf.EmfMetricLoggingPublisher:43 - { "_aws": { "Timestamp": 1752249513975, "LogGroupName": "/aws/lambda/GameId", "CloudWatchMetrics": [ { "Namespace": "namespace", "Dimensions": [ [ "OperationName", "ServiceId" ] ], "Metrics": [ { "Name": "AvailableConcurrency" }, { "Name": "PendingConcurrencyAcquires" }, { "Name": "ServiceCallDuration", "Unit": "Milliseconds" }, { "Name": "EndpointResolveDuration", "Unit": "Milliseconds" }, { "Name": "MaxConcurrency" }, { "Name": "BackoffDelayDuration", "Unit": "Milliseconds" }, { "Name": "MarshallingDuration", "Unit": "Milliseconds" }, { "Name": "LeasedConcurrency" }, { "Name": "SigningDuration", "Unit": "Milliseconds" }, { "Name": "ConcurrencyAcquireDuration", "Unit": "Milliseconds" }, { "Name": "ApiCallSuccessful" }, { "Name": "RetryCount" }, { "Name": "UnmarshallingDuration", "Unit": "Milliseconds" }, { "Name": "ApiCallDuration", "Unit": "Milliseconds" }, { "Name": "CredentialsFetchDuration", "Unit": "Milliseconds" } ] } ] }, "AvailableConcurrency": 0, "PendingConcurrencyAcquires": 0, "OperationName": "PutItem", "ServiceCallDuration": 1339, "EndpointResolveDuration": 81, "MaxConcurrency": 50, "BackoffDelayDuration": 0, "ServiceId": "DynamoDB", "MarshallingDuration": 181, "LeasedConcurrency": 1, "SigningDuration": 184, "ConcurrencyAcquireDuration": 83, "ApiCallSuccessful": 1, "RetryCount": 0, "UnmarshallingDuration": 85, "ApiCallDuration": 1880, "CredentialsFetchDuration": 138 } ``` `EmfMetricLoggingPublisher.Builder` 的 [API 文档](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.Builder.html)显示了您可以使用的配置选项。 您也可以为单个请求启用 EMF 指标日志记录，如[所 CloudWatchMetricPublisher示](metric-pub-impl-cwmp.md#enable-metrics-for-a-specific-request)。 **后续步骤：**对于长时间运行的应用程序，请参阅[从长时间运行的应用程序发布 SDK 指标](metric-pub-impl-cwmp.md)以发布 CloudWatch基于基础的指标。 # 使用向控制台输出 SDK 指标 AWS SDK for Java 2.x `[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)` 实现将指标直接输出到应用程序的控制台或日志文件。这种方法非常适合开发、调试和了解 SDK 收集的指标，而无需像 Amazon 这样的外部服务 CloudWatch。 与 `CloudWatchMetricPublisher` 和 `EmfMetricLoggingPublisher` 不同，`LoggingMetricPublisher` 提供即时输出，没有延迟或外部依赖项。这使其非常适合用于本地开发和故障排除场景。 ## 何时使用 LoggingMetricPublisher 在需要执行以下操作时使用 `LoggingMetricPublisher`： + 在开发过程中调试指标收集 + 了解 SDK 为您的运营收集了哪些指标 + 在本地排查性能问题 + 在没有外部服务依赖项的情况下测试指标收集 + 立即在控制台或日志文件中查看指标 **注意** 不建议将 `LoggingMetricPublisher` 用于需要持久指标存储和分析功能的生产环境中。 ## 为指标设置控制台日志记录 要查看 `LoggingMetricPublisher` 输出，请将您的日志记录框架配置为显示 `INFO` 级别消息。以下 `log4j2.xml` 配置可确保指标显示在控制台中： ``` ``` 此配置指示 SDK 在 `INFO` 级别将指标输出到控制台。`LoggingMetricPublisher` 记录器配置可确保即使根记录器使用更高的级别（如 `WARN` 或 `ERROR`），也能显示指标输出。 ## 为服务客户端启用控制台指标 以下示例演示如何创建 `LoggingMetricPublisher` 并与 Amazon Simple Storage Service 客户端一起使用： ``` import software.amazon.awssdk.metrics.LoggingMetricPublisher; import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; // Create a LoggingMetricPublisher with default settings. MetricPublisher metricPublisher = LoggingMetricPublisher.create(); // Add the publisher to your service client. S3Client s3Client = S3Client.builder() .region(Region.US_EAST_1) .overrideConfiguration(config -> config.addMetricPublisher(metricPublisher)) .build(); // Make requests - metrics will appear in your console. s3Client.listBuckets(); // Clean up resources. metricPublisher.close(); s3Client.close(); ``` ## 选择指标输出格式 `LoggingMetricPublisher` 支持两种输出格式： + **PLAIN 格式（默认）：**以紧凑的单行形式输出指标 + **PRETTY 格式：**以多行、用户可读的格式输出指标 以下示例演示如何使用 PRETTY 格式，以便在开发过程中更轻松地读取输出： ``` import org.slf4j.event.Level; import software.amazon.awssdk.metrics.LoggingMetricPublisher; // Create a LoggingMetricPublisher with PRETTY format. MetricPublisher prettyMetricPublisher = LoggingMetricPublisher.create( Level.INFO, LoggingMetricPublisher.Format.PRETTY ); // Use with your service client. S3Client s3Client = S3Client.builder() .region(Region.US_EAST_1) .overrideConfiguration(config -> config.addMetricPublisher(prettyMetricPublisher)) .build(); ``` ## 完整示例 以下示例演示了通过两种方式来使用 `LoggingMetricPublisher`： + 在服务客户端级别 + 对于单个请求 ``` import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.slf4j.event.Level; import software.amazon.awssdk.metrics.LoggingMetricPublisher; import software.amazon.awssdk.metrics.MetricPublisher; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.s3.model.ListBucketsRequest; import software.amazon.awssdk.services.s3.model.ListBucketsResponse; /** * Demonstrates how to use LoggingMetricPublisher with AWS S3 SDK for Java 2.x. *

* This demo focuses on the S3 listBuckets operation to show how metrics are collected * and logged to the console for development and debugging purposes. *

* LoggingMetricPublisher is ideal for: * - Development and debugging * - Console output for troubleshooting * - Understanding what metrics are being collected * - Testing metric collection without external dependencies */ public class S3LoggingMetricPublisherDemo { private static final Logger logger = LoggerFactory.getLogger(S3LoggingMetricPublisherDemo.class); public static void main(String[] args) { S3LoggingMetricPublisherDemo demo = new S3LoggingMetricPublisherDemo(); demo.demonstrateUsage(); } /** * Demonstrates basic usage with S3Client and metrics enabled at the client level. */ private void demonstrateUsage() { // Create a LoggingMetricPublisher with default settings. The SDK logs metrics as text in a single line. // The default settings are equivalent to using `LoggingMetricPublisher.Format.PLAIN`. MetricPublisher metricPublisher = LoggingMetricPublisher.create(); // Create an S3 client with metrics enabled. try (S3Client s3Client = S3Client.builder() .region(Region.US_EAST_1) .overrideConfiguration(config -> config.addMetricPublisher(metricPublisher)) .build()) { // Make the listBuckets request - metrics will be logged to console. ListBucketsResponse response = s3Client.listBuckets(ListBucketsRequest.builder().build()); // The next block shows the using a different LoggingMetricPublisher with a `PRETTY` format. // Since the metric publisher is added to the request using the `overrideConfiguration`, this formatting // applies only to the one request. try { s3Client.listBuckets(ListBucketsRequest.builder() .overrideConfiguration(config -> config .addMetricPublisher(LoggingMetricPublisher.create( Level.INFO, LoggingMetricPublisher.Format.PRETTY))) .build()); } catch (Exception e) { logger.info("Request failed with metrics logged: {}", e.getMessage()); } logger.info("Found {} buckets in your AWS account.", response.buckets().size()); } catch (Exception e) { logger.error("Error during S3 operation: {}", e.getMessage()); logger.info("Note: This is expected if AWS credentials are not configured."); } // Close the metric publisher to flush any remaining metrics. metricPublisher.close(); } } ``` 该代码将以下内容记录到控制台： ``` INFO LoggingMetricPublisher - Metrics published: MetricCollection(name=ApiCall, metrics=[MetricRecord(metric=MarshallingDuration, value=PT0.005409792S), MetricRecord(metric=RetryCount, value=0), MetricRecord(metric=ApiCallSuccessful, value=true), MetricRecord(metric=OperationName, value=ListBuckets), MetricRecord(metric=EndpointResolveDuration, value=PT0.000068S), MetricRecord(metric=ApiCallDuration, value=PT0.163802958S), MetricRecord(metric=CredentialsFetchDuration, value=PT0.145686542S), MetricRecord(metric=ServiceEndpoint, value=https://s3.amazonaws.com), MetricRecord(metric=ServiceId, value=S3)], children=[MetricCollection(name=ApiCallAttempt, metrics=[MetricRecord(metric=TimeToFirstByte, value=PT0.138816S), MetricRecord(metric=SigningDuration, value=PT0.007803459S), MetricRecord(metric=ReadThroughput, value=165153.96002660287), MetricRecord(metric=ServiceCallDuration, value=PT0.138816S), MetricRecord(metric=AwsExtendedRequestId, value=e13Swj3uwn0qP1Oz+m7II5OGq7jf8xxT8H18iDfRBCQmDg+gU4ek91Xrsl8XxRLROlIzCAPQtsQF0DAAWOb8ntuKCzX2AJdj), MetricRecord(metric=HttpStatusCode, value=200), MetricRecord(metric=BackoffDelayDuration, value=PT0S), MetricRecord(metric=TimeToLastByte, value=PT0.148915667S), MetricRecord(metric=AwsRequestId, value=78AW9BM7SWR6YMGB)], children=[MetricCollection(name=HttpClient, metrics=[MetricRecord(metric=MaxConcurrency, value=50), MetricRecord(metric=AvailableConcurrency, value=0), MetricRecord(metric=LeasedConcurrency, value=1), MetricRecord(metric=ConcurrencyAcquireDuration, value=PT0.002623S), MetricRecord(metric=PendingConcurrencyAcquires, value=0), MetricRecord(metric=HttpClientName, value=Apache)], children=[])])]) INFO LoggingMetricPublisher - [4e6f2bb5] ApiCall INFO LoggingMetricPublisher - [4e6f2bb5] ┌──────────────────────────────────────────┐ INFO LoggingMetricPublisher - [4e6f2bb5] │ MarshallingDuration=PT0.000063S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ RetryCount=0 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ApiCallSuccessful=true │ INFO LoggingMetricPublisher - [4e6f2bb5] │ OperationName=ListBuckets │ INFO LoggingMetricPublisher - [4e6f2bb5] │ EndpointResolveDuration=PT0.000024375S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ApiCallDuration=PT0.018463083S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ CredentialsFetchDuration=PT0.000022334S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceEndpoint=https://s3.amazonaws.com │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceId=S3 │ INFO LoggingMetricPublisher - [4e6f2bb5] └──────────────────────────────────────────┘ INFO LoggingMetricPublisher - [4e6f2bb5] ApiCallAttempt INFO LoggingMetricPublisher - [4e6f2bb5] ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ INFO LoggingMetricPublisher - [4e6f2bb5] │ TimeToFirstByte=PT0.0165575S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ SigningDuration=PT0.000301125S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ReadThroughput=1195591.792850103 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceCallDuration=PT0.0165575S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ AwsExtendedRequestId=3QI1eenRuokdszWqZBmBMDUmko6FlSmHkM+CUMNMeLor7gJml4D4lv6QXUZ1zWoTgG+tHbr6yo2vHdz4h1P8PDovvtMFRCeB │ INFO LoggingMetricPublisher - [4e6f2bb5] │ HttpStatusCode=200 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ BackoffDelayDuration=PT0S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ TimeToLastByte=PT0.017952625S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ AwsRequestId=78AVFAF795AAWAXH │ INFO LoggingMetricPublisher - [4e6f2bb5] └───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ INFO LoggingMetricPublisher - [4e6f2bb5] HttpClient INFO LoggingMetricPublisher - [4e6f2bb5] ┌───────────────────────────────────────┐ INFO LoggingMetricPublisher - [4e6f2bb5] │ MaxConcurrency=50 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ AvailableConcurrency=0 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ LeasedConcurrency=1 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ ConcurrencyAcquireDuration=PT0.00004S │ INFO LoggingMetricPublisher - [4e6f2bb5] │ PendingConcurrencyAcquires=0 │ INFO LoggingMetricPublisher - [4e6f2bb5] │ HttpClientName=Apache │ INFO LoggingMetricPublisher - [4e6f2bb5] └───────────────────────────────────────┘ INFO S3LoggingMetricPublisherDemo - Found 6 buckets in your AWS account. ``` ### 该示例的其他构件 Maven `pom.xml` 文件 ``` 4.0.0 com.example s3-logging-metric-publisher-demo 1.0.0 jar AWS S3 LoggingMetricPublisher Demo Demonstrates how to use LoggingMetricPublisher with AWS S3 SDK for Java 2.x 17 17 UTF-8 2.31.66 2.24.3 software.amazon.awssdk bom ${aws.java.sdk.version} pom import org.apache.logging.log4j log4j-bom ${log4j.version} pom import software.amazon.awssdk s3 org.apache.logging.log4j log4j-slf4j2-impl org.apache.logging.log4j log4j-core org.apache.maven.plugins maven-compiler-plugin 3.13.0 17 17 ``` `Log4j2.xml` 配置文件 ``` ``` 这些指标包括计时信息、服务详细信息、操作名称和 HTTP 状态代码，可帮助您了解应用程序的 AWS API 使用模式。 ## 后续步骤 在使用 `LoggingMetricPublisher` 进行开发和调试之后，请考虑在生产环境中使用以下选项： + 对于长时间运行的应用程序，使用[CloudWatchMetricPublisher](metric-pub-impl-cwmp.md)向 Amazon 发送指标以 CloudWatch 供分析和提醒 + 对于 AWS Lambda 函数，使用[EmfMetricLoggingPublisher](metric-pub-impl-emf.md)以 CloudWatch 嵌入式指标格式发布指标 # AWS SDK for Java 2.x：全面的指标参考 借助 AWS SDK for Java 2.x，您可以从应用程序中的服务客户端收集指标，然后将这些指标发布（输出）到 [Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)。 这些表列出了您可以收集的指标以及任何 HTTP 客户端使用要求。 有关为 SDK 启用和配置指标的更多信息，请参阅[启用 SDK 指标](metrics.md)。 ## 每次请求收集的指标 | 指标名称 | 说明 | Type | | --- | --- | --- | | ApiCallDuration | API 调用的持续时间。这包括所有已发起的调用尝试。 | 持续时间\$1 | | ApiCallSuccessful | 如果 API 调用成功则为 true，否则为 false。 | 布尔值 | | CredentialsFetchDuration | 获取 API 调用的签名凭证的持续时间。 | 持续时间\$1 | | EndpointResolveDuration | 解析 API 调用所用端点的持续时间。 | 持续时间\$1 | | MarshallingDuration | 将 SDK 请求封送到 HTTP 请求的持续时间。 | 持续时间\$1 | | OperationName | 所调用服务操作的名称。 | 字符串 | | RetryCount | SDK 在执行请求时自动重试的次数。0 表示该请求第一次就成功了，没有进行任何重试。 有关配置重试行为的更多信息，请参阅[重试策略](retry-strategy.md#retry-strategies)。 | 整数 | | ServiceId | 服务的唯一 ID。 | 字符串 | | ServiceEndpoint | 服务的端点。 | URI | | TokenFetchDuration | 获取 API 调用的签名凭证的持续时间。 | 持续时间\$1 | \$1[java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html)。 ## 为每次请求尝试收集的指标 每个 API 调用可能需要多次尝试才能收到响应。每次尝试都会收集这些指标。 ### 核心指标 | 指标名称 | 说明 | Type | | --- | --- | --- | | AwsExtendedRequestId | 服务请求的扩展请求 ID。 | 字符串 | | AwsRequestId | 服务请求的请求 ID。 | 字符串 | | BackoffDelayDuration | 在这次 API 调用尝试之前 SDK 已等待的持续时间。该值基于客户端上 `[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html)` 设置。有关更多信息，请参阅本指南的[重试策略](retry-strategy.md#retry-strategies)部分。 | 持续时间\$1 | | ErrorType | 进行调用尝试时发生的错误类型。 以下是可能的值： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/metrics-list.html) | 字符串 | | ReadThroughput | 客户端的读取吞吐量，定义为 `NumberOfResponseBytesRead / (TTLB - TTFB)`。此值以每秒字节数为单位。 请注意，此指标仅测量从 `ResponseTransformer` 或 `AsyncResponseTransformer` 内读取的字节。计算中不包括在转换器外部读取的数据（例如，当响应流作为转换器的结果返回时）。 | 双精度 | | WriteThroughput | 客户端的写入吞吐量，定义为`RequestBytesWritten / (LastByteWrittenTime - FirstByteWrittenTime)`。此值以每秒字节数为单位。 该指标衡量 SDK 向 HTTP 客户端提供请求正文的速率。它不包括连接设置、TLS 握手时间和服务器处理时间。仅针对具有流媒体主体（例如 S3）的请求报告此指标 PutObject。 请注意，此指标未考虑 HTTP 客户端层中的缓冲情况。如果 HTTP 客户端在发送数据之前缓冲数据，则实际网络传输速率可能会更低。该指标代表网络吞吐量的上限。 | 双精度 | | ServiceCallDuration | 连接到服务（或从连接池中获取连接）、发送序列化请求和接收初始响应（例如 HTTP 状态码和标头）的持续时间。这不包括从服务中读取整个响应的时间。 | 持续时间\$1 | | SigningDuration | 签署 HTTP 请求的持续时间。 | 持续时间\$1 | | TimeToFirstByte | 从将 HTTP 请求发送到服务（包括获取连接），到接收响应中标头的第一个字节的持续时间。 | 持续时间\$1 | | TimeToLastByte | 从将 HTTP 请求发送到服务（包括获取连接），到接收响应的最后一个字节的持续时间。 请注意，对于 APIs 返回的流媒体响应，此指标跨越了直到`ResponseTransformer`或`AsyncResponseTransformer`完成的时间。 | 持续时间\$1 | | UnmarshallingDuration | 将 HTTP 响应解组到 SDK 响应的持续时间。 注意：对于流式操作，这不包括读取响应有效载荷的时间。 | 持续时间\$1 | \$1[java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html)。 ### HTTP 指标 | 指标名称 | 说明 | Type | 需要 HTTP 客户端\$1 | | --- | --- | --- | --- | | AvailableConcurrency | 在不与目标服务器建立新连接的情况下，HTTP 客户端支持的额外并发请求数。 对于 HTTP/1 操作，这等于与服务建立的空闲 TCP 连接的数量。对于 HTTP/2 操作，这等于空闲流的数量。 注意：此值因 HTTP 客户端实现而异： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/metrics-list.html) 该值的范围限定于单个 HTTP 客户端实例，不包括同一 JVM 中其他 HTTP 客户端的并发。 | 整数 | Apache、Netty、CRT | | ConcurrencyAcquireDuration | 从连接池中获取通道的持续时间。 对于 HTTP/1 操作，通道等于 TCP 连接。对于 HTTP/2 操作，通道等于 HTTP/2 流通道。 获取新通道可能包括以下时间： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/metrics-list.html) | 持续时间\$1 | Apache、Netty、CRT | | HttpClientName | 用于请求的 HTTP 的名称。 | 字符串 | Apache、Netty、CRT | | HttpStatusCode | HTTP 响应的状态代码。 | 整数 | 任何 | | LeasedConcurrency | HTTP 客户端当前执行的请求数。 对于 HTTP/1 操作，这等于与服务建立的活跃 TCP 连接的数量（不包括空闲连接）。对于 HTTP/2 操作，这等于服务的活动 HTTP 流的数量（不包括空闲流容量）。 注意：此值因 HTTP 客户端实现而异： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/metrics-list.html) 该值的范围限定于单个 HTTP 客户端实例，不包括同一 JVM 中其他 HTTP 客户端的并发。 | 整数 | Apache、Netty、CRT | | LocalStreamWindowSize | 执行此请求的流的本地 HTTP/2 窗口大小（以字节为单位）。 | 整数 | Netty | | MaxConcurrency | HTTP 客户端支持的最大并发请求数。 对于 HTTP/1 操作，这等于 HTTP 客户端可以汇集的最大 TCP 连接数。对于 HTTP/2 操作，这等于 HTTP 客户端可以汇集的最大流数。 注意：此值因 HTTP 客户端实现而异： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/metrics-list.html) 该值的范围限定于单个 HTTP 客户端实例，不包括同一 JVM 中其他 HTTP 客户端的并发。 | 整数 | Apache、Netty、CRT | | PendingConcurrencyAcquires | 等待 HTTP 客户端并发的请求数。 对于 HTTP/1 操作，这等于等待 TCP 连接建立或从连接池返回的请求数。对于 HTTP/2 操作，这等于等待来自连接池的新流（可能还有新 HTTP/2 连接）的请求数。 注意：此值因 HTTP 客户端实现而异： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/sdk-for-java/latest/developer-guide/metrics-list.html) 该值的范围限定于单个 HTTP 客户端实例，不包括同一 JVM 中其他 HTTP 客户端的并发。 | 整数 | Apache、Netty、CRT | | RemoteStreamWindowSize | 执行此请求的流的远程 HTTP/2 窗口大小（以字节为单位）。 | 整数 | Netty | \$1[java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html)。 列中所用术语解释： + Apache：基于 Apache 的 HTTP 客户端（`[ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html)`） + Netty：基于 Netty 的 HTTP 客户端（`[NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)`） + CRT： AWS 基于 CRT 的 HTTP 客户端 () `[AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)` + 任意：指标数据的收集不依赖于 HTTP 客户端；这包括 URLConnection基于的 HTTP 客户端 (`[UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)`)