本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 Amazon CloudWatch 監控 Kinesis 用戶端程式庫
<a name="monitoring-with-kcl"></a>

適用於 Amazon Kinesis Data Streams 的 [Kinesis Client Library](https://docs.aws.amazon.com/kinesis/latest/dev/developing-consumers-with-kcl.html) (KCL) 會代您發佈自訂的 Amazon CloudWatch 指標，並使用您的 KCL 應用程式的名稱作為命名空間。然後，您可以導覽至 [CloudWatch 主控台](https://console.aws.amazon.com/cloudwatch/)，並選擇**自訂指標**來檢視這些指標。如需詳細資訊，請參閱《Amazon CloudWatch 使用者指南》**中的[發佈自訂指標](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/publishingMetrics.html)。

這是 KCL 將指標上傳到 CloudWatch 的名目費用；具體而言，適用* Amazon CloudWatch 自訂指標*和 *Amazon CloudWatch API 請求*費用。如需詳細資訊，請參閱 [Amazon CloudWatch 定價](https://aws.amazon.com/cloudwatch/pricing/)。

**Topics**
+ [指標和命名空間](#metrics-namespace)
+ [指標層級和維度](#metric-levels)
+ [指標組態](#metrics-config)
+ [指標清單](#kcl-metrics-list)

## 指標和命名空間
<a name="metrics-namespace"></a>

用來上傳指標的命名空間是當您啟動 KCL 時指定的應用程式名稱。

## 指標層級和維度
<a name="metric-levels"></a>

有兩種選項可控制上傳到 CloudWatch 的指標：

指標層級  
每個指標會獲指派個別層級。設定指標報告層級時，具有單一層級的指標若低於報告層級即不會傳送到 CloudWatch。層級為：`NONE`、`SUMMARY` 和 `DETAILED`。預設設定為 `DETAILED`；亦即，所有指標都會傳送到 CloudWatch。`NONE` 報告層級表示不會傳送任何指標。如需有關指派哪些層級給哪些指標的詳細資訊，請參閱 [指標清單](#kcl-metrics-list)。

已啟用的維度  
每個 KCL 指標的關聯維度也會傳送到 CloudWatch。在 KCL 2.x 中，如果 KCL 設定為處理單一資料串流，則預設會啟用所有指標維度 (`Operation`、`ShardId`、和 `WorkerIdentifier`)。此外，在 KCL 2.x 中，如果 KCL 設定為處理單一資料串流，則無法停用 `Operation` 維度。在 KCL 2.x 中，如果 KCL 設定為處理多個資料串流，則預設會啟用所有指標維度 (`Operation`、`StreamId`、 `ShardId`和 `WorkerIdentifier`)。此外，在 KCL 2.x 中，如果 KCL 設定為處理多個資料串流，則無法停用 `Operation`和`StreamId`維度。`StreamId`維度僅適用於每個碎片指標。  
 在 KCL 1.x 中，預設情況下，只有 `Operation` 和 `ShardId` 維度是啟用的，`WorkerIdentifier` 維度是停用的。在 KCL 1.x 中，無法停用該 `Operation` 維度。  
如需 CloudWatch 指標維度的詳細資訊，請參閱《Amazon CloudWatch 使用者指南》**中 Amazon CloudWatch 概念主題下的[維度](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/cloudwatch_concepts.html#Dimension)部分。  
啟用 `WorkerIdentifier` 維度時，如果每次特定 KCL 工作者重新啟動時對工作者 ID 屬性使用不同的值，即會隨著新 `WorkerIdentifier` 維度值將新的指標集傳送到 CloudWatch。如果您需要 `WorkerIdentifier` 維度值在特定 KCL 工作者重新啟動時是相同的，您必須在每個工作者的初始化期間明確指定相同的工作者 ID 值。請注意，每個作用中 KCL 工作者的工作者 ID 值，在所有 KCL 工作者間必須是唯一的。

## 指標組態
<a name="metrics-config"></a>

指標層級和啟用的維度可以使用 KinesisClientLibConfiguration 執行個體加以設定，會在啟動 KCL 應用程式時將該執行個體傳送至工作者。在 MultiLangDaemon 情況下，您可以在 .properties 檔案中指定用於啟動 MultiLangDaemon KCL 應用程式的 `metricsLevel` 和 `metricsEnabledDimensions` 屬性。

您可以對指標層級指派下列三個值中的其中之一：NONE、SUMMARY 或 DETAILED。啟用的維度值必須是對 CloudWatch 指標允許之維度以逗號分隔字串的清單。KCL 應用程式使用的維度為 `Operation`、`ShardId` 及 `WorkerIdentifier`。

## 指標清單
<a name="kcl-metrics-list"></a>

下表列出 KCL 指標，依範圍和操作分組。

**Topics**
+ [Per-KCL-application指標](#kcl-metrics-per-app)
+ [每個工作者的指標](#kcl-metrics-per-worker)
+ [每個碎片指標](#kcl-metrics-per-shard)

### Per-KCL-application指標
<a name="kcl-metrics-per-app"></a>

這些指標會在應用程式範圍內的所有 KCL 工作者間彙總，如 Amazon CloudWatch 命名空間所定義。

**Topics**
+ [LeaseAssignmentManager](#lease-assignment-manager)
+ [InitializeTask](#init-task)
+ [ShutdownTask](#shutdown-task)
+ [ShardSyncTask](#shard-sync-task)
+ [BlockOnParentTask](#block-parent-task)
+ [PeriodicShardSyncManager](#periodic-task)
+ [MultistreamTracker](#multi-task)

#### LeaseAssignmentManager
<a name="lease-assignment-manager"></a>

`LeaseAssignmentManager` 此操作負責將租用指派給工作者，並在工作者之間重新平衡租用，以實現工作者資源的均勻使用率。此操作的邏輯包括從租用資料表讀取租用相關的中繼資料，以及從工作者指標資料表讀取指標，以及執行租用指派。


| 指標 | Description | 
| --- | --- | 
|  LeaseAndWorkerMetricsLoad.Time  |  載入租用指派管理員 (LAM) 中的所有租用和工作者指標項目所需的時間，這是 KCL 3.x 中引入的新租用指派和負載平衡演算法。 指標層級：詳細 單位：毫秒  | 
| TotalLeases |  目前 KCL 應用程式的租用總數。 指標層級：摘要 單位：Count  | 
| NumWorkers |  目前 KCL 應用程式中的工作者總數。 指標層級：摘要 單位：Count  | 
|  AssignExpiredOrUnassignedLeases.Time  |  執行過期租用的記憶體內指派的時間。 指標層級：詳細 單位：毫秒  | 
| LeaseSpillover |  由於達到租用數量上限或每個工作者輸送量上限而未指派的租用數量。 指標層級：摘要 單位：Count  | 
|  BalanceWorkerVariance.Time  |  在工作者之間執行記憶體內平衡租用的時間。 指標層級：詳細 單位：毫秒  | 
|  NumOfLeasesReassignment  |  目前重新指派反覆運算中所做的租用重新指派總數。 指標層級：摘要 單位：Count  | 
|  FailedAssignmentCount  |  AssignLease 呼叫 DynamoDB 租用資料表中的失敗次數。 指標層級：詳細 單位：Count  | 
|  ParallelyAssignLeases.Time  |  排清 DynamoDB 租用資料表新指派的時間。 指標層級：詳細 單位：毫秒  | 
|  ParallelyAssignLeases.Success  |  新指派成功排清的數量。 指標層級：詳細 單位：Count  | 
|  TotalStaleWorkerMetricsEntry  |  必須清除的工作者指標項目總數。 指標層級：詳細 單位：Count  | 
| StaleWorkerMetricsCleanup.Time |  從 DynamoDB 工作者指標資料表執行工作者指標項目刪除的時間。 指標層級：詳細 單位：毫秒  | 
| 時間 |  `LeaseAssignmentManager` 操作所花費的時間。 指標層級：摘要 單位：毫秒  | 
| 成功 |  成功完成 `LeaseAssignmentManager` 操作的次數。 指標層級：摘要 單位：Count  | 
| ForceLeaderRelease |  表示租用指派管理員連續失敗 3 次，且領導者工作者正在釋出領導。 指標層級：摘要 單位：Count  | 
|  NumWorkersWithInvalidEntry  |  視為無效的工作者指標項目數目。 指標層級：摘要 單位：Count  | 
|  NumWorkersWithFailingWorkerMetric  |  具有 -1 的工作者指標項目數目 （表示工作者指標值不可用） 作為工作者指標的其中一個值。 指標層級：摘要 單位：Count  | 
|  LeaseDeserializationFailureCount  |  租用資料表中無法還原序列化的租用項目。 指標層級：摘要 單位：Count  | 

#### InitializeTask
<a name="init-task"></a>

`InitializeTask` 操作負責初始化 KCL 應用程式的記錄處理器。此操作的邏輯包含取得來自 Kinesis Data Streams 的碎片反覆運算器和初始化記錄處理器。


| 指標 | Description | 
| --- | --- | 
| KinesisDataFetcher.getIterator.Success |  每一 KCL 應用程式成功 `GetShardIterator` 操作的數量。 指標層級：詳細 單位：Count  | 
| KinesisDataFetcher.getIterator.Time |  指定 KCL 應用程式的每個 `GetShardIterator` 操作耗費的時間。 指標層級：詳細 單位：毫秒  | 
| RecordProcessor.initialize.Time |  記錄處理器的 initialize 方法耗費的時間。 指標層級：摘要 單位：毫秒  | 
| 成功 |  成功的記錄處理器初始化的數量。 指標層級：摘要 單位：Count  | 
| 時間 |  KCL 工作者的記錄處理器初始化耗費的時間。 指標層級：摘要 單位：毫秒  | 

#### ShutdownTask
<a name="shutdown-task"></a>

`ShutdownTask` 操作會初始化碎片處理的關閉序列。因為碎片分割或合併，或當工作者遺失碎片租用時可能會發生此情況。在這兩種情況下，會叫用記錄處理器 `shutdown()` 函數。當碎片分割或合併造成建立一或兩個新的碎片的情況下，也會發現新的碎片。


| 指標 | Description | 
| --- | --- | 
| CreateLease.Success |  在父碎片關閉之後將新子碎片成功新增到 KCL 應用程式 DynamoDB 資料表的次數。 指標層級：詳細 單位：Count  | 
| CreateLease.Time |  在 KCL 應用程式 DynamoDB 資料表中新增子碎片資訊耗費的時間。 指標層級：詳細 單位：毫秒  | 
| UpdateLease.Success |  記錄處理器關閉期間成功的最終檢查點數量。 指標層級：詳細 單位：Count  | 
| UpdateLease.Time |  記錄處理器關閉期間檢查點操作耗費的時間。 指標層級：詳細 單位：毫秒  | 
| RecordProcessor.shutdown.Time |  記錄處理器的 shutdown 方法耗費的時間。 指標層級：摘要 單位：毫秒  | 
| 成功 |  成功關閉任務的數量。 指標層級：摘要 單位：Count  | 
| 時間 |  KCL 工作者的關閉任務耗費的時間。 指標層級：摘要 單位：毫秒  | 

#### ShardSyncTask
<a name="shard-sync-task"></a>

`ShardSyncTask` 操作會探索對 Kinesis 資料串流碎片資訊的變更，使得 KCL 應用程式可以處理新的碎片。


| 指標 | Description | 
| --- | --- | 
| CreateLease.Success |  成功嘗試將新的碎片資訊新增至 KCL 應用程式 DynamoDB 資料表的數量。 指標層級：詳細 單位：Count  | 
| CreateLease.Time |  在 KCL 應用程式 DynamoDB 資料表中新增碎片資訊耗費的時間。 指標層級：詳細 單位：毫秒  | 
| 成功 |  成功的碎片同步操作數量。 指標層級：摘要 單位：Count  | 
| 時間 |  碎片同步操作耗費的時間。 指標層級：摘要 單位：毫秒  | 

#### BlockOnParentTask
<a name="block-parent-task"></a>

如果碎片分割或與其他碎片合併，則會建立新的子碎片。`BlockOnParentTask` 操作可確保新碎片的記錄處理不會開始，直到 KCL 已完全處理父碎片為止。


| 指標 | Description | 
| --- | --- | 
| 成功 |  成功的父碎片完成檢查數量。 指標層級：摘要 單位：Count  | 
| 時間 |  父碎片完成耗費的時間。 指標層級：摘要 單位：毫秒  | 

#### PeriodicShardSyncManager
<a name="periodic-task"></a>

`PeriodicShardSyncManager` 負責檢查 KCL 取用者應用程式正在處理的資料串流，識別具有部分租用的資料串流，並將其移交以進行同步處理。

當 KCL 設定為處理單一資料串流 (然後將 NumStreamStoSync 和 NumStreamsWithPartialLeases 設定為 1)，以及將 KCL 設定為處理多個資料串流時，可以使用下列指標。


| 指標 | Description | 
| --- | --- | 
| NumStreamsToSync |  消費者應用程式處理的資料串流數目 （每個 AWS 帳戶），其中包含部分租用且必須遞交以進行同步處理。 指標層級：摘要 單位：Count  | 
| NumStreamsWithPartialLeases |  消費者應用程式正在處理的資料串流數目 （每個 AWS 帳戶），其中包含部分租用。 指標層級：摘要 單位：Count  | 
| 成功 |  `PeriodicShardSyncManager` 能夠在取用者應用程式正在處理的資料串流中成功識別部分租用的次數。 指標層級：摘要 單位：Count  | 
| 時間 |  檢查取用者應用程式正在處理的資料串流`PeriodicShardSyncManager`所需的時間量 （以毫秒為單位），以判斷哪些資料串流需要碎片同步處理。 指標層級：摘要 單位：毫秒  | 

#### MultistreamTracker
<a name="multi-task"></a>

此 `MultistreamTracker` 介面可讓您建置可同時處理多個資料串流的 KCL 取用者應用程式。


| 指標 | Description | 
| --- | --- | 
| DeletedStreams.Count |  在此期間刪除的資料串流數目。 指標層級：摘要 單位：Count  | 
| ActiveStreams.Count |  正在處理的作用中資料串流數目。 指標層級：摘要 單位：Count  | 
| StreamsPendingDeletion.Count |  擱置刪除的資料串流數目 (依據 `FormerStreamsLeasesDeletionStrategy`)。 指標層級：摘要 單位：Count  | 

### 每個工作者的指標
<a name="kcl-metrics-per-worker"></a>

系統會針對耗用來自 Kinesis 資料串流 (例如：Amazon EC2 執行個體) 之資料的所有記錄處理器彙總這些指標。

**Topics**
+ [WorkerMetricStatsReporter](#worker-metrics-stats)
+ [LeaseDiscovery](#lease-discovery)
+ [RenewAllLeases](#renew-leases)
+ [TakeLeases](#take-leases)

#### WorkerMetricStatsReporter
<a name="worker-metrics-stats"></a>

`WorkerMetricStatReporter` 操作負責定期將目前工作者的指標發佈至工作者指標表。`LeaseAssignmentManager` 操作使用這些指標來執行租用指派。


| 指標 | Description | 
| --- | --- | 
|  InMemoryMetricStatsReporterFailure  |  由於某些工作者指標失敗，擷取記憶體內工作者指標值的失敗次數。 指標層級：摘要 單位：Count  | 
|  WorkerMetricStatsReporter.Time  |  `WorkerMetricsStats` 操作所花費的時間。 指標層級：摘要 單位：毫秒  | 
|  WorkerMetricStatsReporter.Success  |  成功完成 `WorkerMetricsStats` 操作的次數。 指標層級：摘要 單位：Count  | 

#### LeaseDiscovery
<a name="lease-discovery"></a>

`LeaseDiscovery` 操作負責識別操作指派給目前工作者的新租用`LeaseAssignmentManager`。此操作的邏輯涉及透過讀取租用資料表的全域次要索引來識別指派給目前工作者的租用。


| 指標 | Description | 
| --- | --- | 
|  ListLeaseKeysForWorker.Time  |  呼叫租用資料表上的全域次要索引，並取得指派給目前工作者的租用金鑰的時間。 指標層級：詳細 單位：毫秒  | 
|  FetchNewLeases.Time  |  從租用資料表擷取所有新租用的時間。 指標層級：詳細 單位：毫秒  | 
|  NewLeasesDiscovered  |  指派給工作者的新租用總數。 指標層級：詳細 單位：Count  | 
|  時間  |  `LeaseDiscovery` 操作所花費的時間。 指標層級：摘要 單位：毫秒  | 
|  成功  |  成功完成 `LeaseDiscovery` 操作的次數。 指標層級：摘要 單位：Count  | 
|  OwnerMismatch  |  來自 GSI 回應和租用資料表一致讀取的擁有者不相符數量。 指標層級：詳細 單位：Count  | 

#### RenewAllLeases
<a name="renew-leases"></a>

`RenewAllLeases` 操作會定期更新特定工作者執行個體擁有的碎片租用。


| 指標 | Description | 
| --- | --- | 
| RenewLease.Success |  成功的工作者租用更新數量。 指標層級：詳細 單位：Count  | 
| RenewLease.Time |  租用更新操作耗費的時間。 指標層級：詳細 單位：毫秒  | 
| CurrentLeases |  在更新所有租用之後，工作者擁有的碎片租用數量。 指標層級：摘要 單位：Count  | 
| LostLeases |  嘗試更新工作者擁有的所有租用之後，遺失的碎片租用數量。 指標層級：摘要 單位：Count  | 
| 成功 |  工作者的租用續約操作成功次數。 指標層級：摘要 單位：Count  | 
| 時間 |  更新工作者所有租用耗費的時間。 指標層級：摘要 單位：毫秒  | 

#### TakeLeases
<a name="take-leases"></a>

`TakeLeases` 操作會平衡所有 KCL 工作者之間的記錄處理。如果目前的 KCL 工作者擁有的碎片較所需的碎片更少，則會從另一個過載的工作者取得碎片租用。


| 指標 | Description | 
| --- | --- | 
| ListLeases.Success |  已成功從 KCL 應用程式 DynamoDB 資料表擷取之所有碎片租用的次數。 指標層級：詳細 單位：Count  | 
| ListLeases.Time |  從 KCL 應用程式 DynamoDB 資料表擷取所有碎片租用耗費的時間。 指標層級：詳細 單位：毫秒  | 
| TakeLease.Success |  工作者成功從其他 KCL 工作者取得碎片租用的次數。 指標層級：詳細 單位：Count  | 
| TakeLease.Time |  更新工作者取得之租用的租用資料表耗費的時間。 指標層級：詳細 單位：毫秒  | 
| NumWorkers |  工作者的總數量，如特定工作者所識別。 指標層級：摘要 單位：Count  | 
| NeededLeases |  目前的工作者對平衡碎片處理負載所需的碎片租用數量。 指標層級：詳細 單位：Count  | 
| LeasesToTake |  工作者將嘗試取得的租用數量。 指標層級：詳細 單位：Count  | 
| TakenLeases |  工作者成功取得的租用數量。 指標層級：摘要 單位：Count   | 
| TotalLeases |  KCL 應用程式正在處理的碎片總數量。 指標層級：詳細 單位：Count  | 
| ExpiredLeases |  任何工作者未處理的碎片總數量，如特定工作者所識別。 指標層級：摘要 單位：Count  | 
| 成功 |  成功完成 `TakeLeases` 操作的次數。 指標層級：摘要 單位：Count  | 
| 時間 |  工作者的 `TakeLeases` 操作耗費的時間。 指標層級：摘要 單位：毫秒  | 

### 每個碎片指標
<a name="kcl-metrics-per-shard"></a>

系統會對單一記錄處理器彙總這些指標。

#### ProcessTask
<a name="process-task"></a>

`ProcessTask` 操作會以目前反覆運算器的位置呼叫 [GetRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetRecords.html)，以從串流擷取記錄並呼叫記錄處理器 `processRecords` 功能。


| 指標 | Description | 
| --- | --- | 
| KinesisDataFetcher.getRecords.Success |  每一 Kinesis 資料串流碎片成功的 `GetRecords` 操作數量。 指標層級：詳細 單位：Count  | 
| KinesisDataFetcher.getRecords.Time |  Kinesis 資料串流碎片的每個 `GetRecords` 操作耗費的時間。 指標層級：詳細 單位：毫秒  | 
| UpdateLease.Success |  記錄處理器針對指定碎片進行的成功檢查點數量。 指標層級：詳細 單位：Count  | 
| UpdateLease.Time |  針對指定碎片的每個檢查點操作耗費的時間。 指標層級：詳細 單位：毫秒  | 
| DataBytesProcessed |  每個 `ProcessTask` 叫用上處理的記錄總大小 (以位元組為單位)。 指標層級：摘要 單位：位元組  | 
| RecordsProcessed |  每個 `ProcessTask` 叫用上處理的記錄數。 指標層級：摘要 單位：Count  | 
| ExpiredIterator |  呼叫 `GetRecords` 時收到的 ExpiredIteratorException 數量。 指標層級：摘要 單位：Count  | 
| MillisBehindLatest | 目前反覆運算器落後碎片中最新記錄 (頂端) 的時間。這個值小於或等於回應中最新記錄與目前時間之間的時間差異。這是碎片與尖端距離的更準確反映，而不是比較上次回應記錄中的時間戳記。此值適用於最新的記錄批次，而不是每個記錄中所有時間戳記的平均值。指標層級：摘要單位：毫秒 | 
| RecordProcessor.processRecords.Time |  記錄處理器的 `processRecords` 方法耗費的時間。 指標層級：摘要 單位：毫秒  | 
| 成功 |  成功的處理任務操作數量。 指標層級：摘要 單位：Count  | 
| 時間 |  處理任務操作耗費的時間。 指標層級：摘要 單位：毫秒  |