本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 從長時間執行的應用程式發佈 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` 檔案中） 設定為使用 版本 `2.14.0` 或更新版本 適用於 Java 的 AWS SDK。
在專案的相依性中，將 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();
}
}
```
**重要**
確保您的應用程式`close`在服務用戶端不再使用時呼叫`[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)`執行個體。否則可能會導致執行緒或檔案描述項洩漏。
## 啟用特定服務用戶端的摘要指標
下列程式碼片段示範如何使用服務用戶端的預設設定啟用 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`方法來指定不同的值。
+ 根據預設，軟體開發套件會發佈摘要指標。摘要指標包含平均值、最小值、最大值、總和和範例計數。透過在 `detailedMetrics`方法中指定一或多個 SDK 指標，SDK 會為每個指標發佈其他資料。此額外資料可讓您在 CloudWatch 中查詢 p90 和 p99 等百分位數統計資料。詳細指標特別適用於延遲指標，例如 `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) 指標。