本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 監控 Kinesis 資料串流
您可以使用下列功能在 Amazon Kinesis Data Streams 中監控資料串流：
+ [CloudWatch 指標](monitoring-with-cloudwatch.md) – Kinesis Data Streams 會向 Amazon CloudWatch 傳送具有每個串流之詳細監控的自訂指標。
+ [Kinesis 代理程式](agent-health.md) – Kinesis 代理程式發佈自訂 CloudWatch 指標，以協助評估代理程式是否如預期運作。
+ [API 記錄](logging-using-cloudtrail.md) – Kinesis Data Streams 使用 AWS CloudTrail 來記錄 API 呼叫，並將資料存放在 Amazon S3 儲存貯體中。
+ [Kinesis Client Library](monitoring-with-kcl.md) – Kinesis Client Library (KCL) 提供每個碎片、工作者和 KCL 應用程式的指標。
+ [Kinesis Producer Library](monitoring-with-kpl.md) – Amazon Kinesis Producer Library (KPL) 提供每個碎片、工作者和 KPL 應用程式的指標。
如需常見監控問題、疑問和故障診斷的詳細資訊，請參閱下列各項：
+ [我應該使用哪些指標來監控 Kinesis Data Streams 問題並進行故障診斷？](https://aws.amazon.com/premiumsupport/knowledge-center/kinesis-data-streams-troubleshoot/)
+ [為什麼 Kinesis Data Streams 中的 IteratorAgeMilliseconds 值不斷增加？](https://aws.amazon.com/premiumsupport/knowledge-center/kinesis-data-streams-iteratorage-metric/)
# 使用 Amazon CloudWatch 監控 Amazon Kinesis Data Streams 服務 Amazon CloudWatch
Amazon Kinesis Data Streams 與 Amazon CloudWatch 整合，因此您可以收集、檢視和分析 Kinesis 資料串流的 CloudWatch 指標。例如，若要追蹤碎片用量，您可以監控 `IncomingBytes` 和 `OutgoingBytes` 指標，並將它們與串流中的碎片數量比較。
您設定的串流指標和碎片層級指標會每分鐘自動收集並推送至 CloudWatch。指標將封存兩週，之後即會捨棄資料。
下表說明 Kinesis 資料串流的基本串流層級和增強之碎片層級監控。
| Type | 說明 |
| --- | --- |
| 基本 (串流層級) | 串流層級資料將每分鐘免費自動傳送。 |
| 增強 (碎片層級) | 碎片層級資料會每分鐘傳送 (需另行支付費用)。若要取得此層級的資料，您必須使用 [EnableEnhancedMonitoring](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_EnableEnhancedMonitoring.html) 操作，特別為串流啟用它。 如需定價的詳細資訊，請參閱 [Amazon CloudWatch 產品頁面](https://aws.amazon.com/cloudwatch)。 |
## Amazon Kinesis Data Streams 維度和指標
Kinesis Data Streams 會以兩個層級將指標傳送至 CloudWatch：串流層級以及選擇性的碎片層級。串流層級指標適用於正常情況下最常見的監控使用案例。碎片層級指標用於特定的監控任務 (一般是與疑難排解相關)，並且是使用 [EnableEnhancedMonitoring](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_EnableEnhancedMonitoring.html) 操作來啟用。
如需從 CloudWatch 指標收集到的統計資料的說明，請參閱 《Amazon CloudWatch 使用者指南》**中的 [CloudWatch 統計資料](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/cloudwatch_concepts.html#Statistic)。
**Topics**
+ [基本串流層級指標](#kinesis-metrics-stream)
+ [增強的碎片層級指標](#kinesis-metrics-shard)
+ [Amazon Kinesis Data Streams 指標的維度](#kinesis-metricdimensions)
+ [建議的 Amazon Kinesis Data Streams 指標](#kinesis-metric-use)
### 基本串流層級指標
`AWS/Kinesis` 命名空間包含下列串流層級指標。
Kinesis Data Streams 會每分鐘將這些串流層級指標傳送給 CloudWatch。這些是一律可用的指標。
| 指標 | Description |
| --- | --- |
| GetRecords.Bytes | 擷取自 Kinesis 串流的位元組數目，這是對指定的期間進行測量。Minimum、Maximum 與 Average 統計資訊代表指定期間內串流之單一 `GetRecords` 操作中的位元組。 分區層級指標名稱：`OutgoingBytes` 維度：StreamName 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：位元組 |
| GetRecords.IteratorAge | 不再使用此指標。請使用 `GetRecords.IteratorAgeMilliseconds`。 |
| GetRecords.IteratorAgeMilliseconds | 對 Kinesis 串流進行之所有 `GetRecords` 呼叫中最後一筆記錄的存留期，這是對指定的期間進行測量。目前時間與將 `GetRecords` 呼叫的最後一筆記錄寫入至串流時之間的差異就是存留期。Minimum 和 Maximum 統計資訊可以用來追蹤 Kinesis 取用者應用程式進度。零值指出所讀取的記錄完全與串流同步。 分區層級指標名稱：`IteratorAgeMilliseconds` 維度：StreamName 統計資訊：Minimum、Maximum、Average、Samples 單位：毫秒 |
| GetRecords.Latency | 每個 `GetRecords` 操作所需的時間，這是對指定的期間進行測量。 維度：StreamName 統計資訊：Minimum、Maximum、Average 單位：毫秒 |
| GetRecords.Records | 擷取自分區的記錄數目，這是對指定的期間進行測量。Minimum、Maximum 與 Average 統計資訊代表指定期間內串流之單一 `GetRecords` 操作中的記錄。 分區層級指標名稱：`OutgoingRecords` 維度：StreamName 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：Count |
| GetRecords.Success | 每個串流的成功 `GetRecords` 操作數目，這是對指定的期間進行測量。 維度：StreamName 統計資訊：Average、Sum、Samples 單位：Count |
| IncomingBytes | 在指定的期間內，成功放入 Kinesis 串流的位元組數目。此指標包含來自 `PutRecord` 與 `PutRecords` 操作的位元組。Minimum、Maximum 與 Average 統計資訊代表指定期間內串流之單一 Put 操作中的位元組。 分區層級指標名稱：`IncomingBytes` 維度：StreamName 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：位元組 |
| IncomingRecords | 在指定的期間內，成功放入 Kinesis 串流的記錄數目。此指標包含來自 `PutRecord` 與 `PutRecords` 操作的記錄計數。Minimum、Maximum 與 Average 統計資訊代表指定期間內串流之單一 Put 操作中的記錄。 分區層級指標名稱：`IncomingRecords` 維度：StreamName 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：Count |
| PutRecord.Bytes | 在指定的期間內，使用 `PutRecord` 操作放入 Kinesis 串流的位元組數目。 維度：StreamName 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：位元組 |
| PutRecord.Latency | 每個 `PutRecord` 操作所需的時間，這是對指定的期間進行測量。 維度：StreamName 統計資訊：Minimum、Maximum、Average 單位：毫秒 |
| PutRecord.Success | 每個 Kinesis 串流的成功 `PutRecord` 操作數目，這是對指定的期間進行測量。Average 會反映成功寫入至串流的百分比。 維度：StreamName 統計資訊：Average、Sum、Samples 單位：Count |
| PutRecords.Bytes | 在指定的期間內，使用 `PutRecords` 操作放入 Kinesis 串流的位元組數目。 維度：StreamName 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：位元組 |
| PutRecords.Latency | 每個 `PutRecords` 操作所需的時間，這是對指定的期間進行測量。 維度：StreamName 統計資訊：Minimum、Maximum、Average 單位：毫秒 |
| PutRecords.Records | 此指標已淘汰。請使用 `PutRecords.SuccessfulRecords`。 維度：StreamName 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：Count |
| PutRecords.Success | 每個 Kinesis 串流中至少有一筆記錄成功的 `PutRecords` 操作數目，這是對指定的期間進行測量。 維度：StreamName 統計資訊：Average、Sum、Samples 單位：Count |
| PutRecords.TotalRecords | 每個 Kinesis 資料串流之 `PutRecords` 操作中的記錄總數，這是對指定的期間進行測量。 維度：StreamName 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：Count |
| PutRecords.SuccessfulRecords | 每個 Kinesis 資料串流之 `PutRecords` 操作中的成功記錄數目，這是對指定的期間進行測量。 維度：StreamName 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：Count |
| PutRecords.FailedRecords | 由於內部失敗，每個 Kinesis 資料串流之 `PutRecords` 操作中遭拒的記錄數目，這是對指定的期間進行測量。偶爾的內部故障是預料中的，應該重試。 維度：StreamName 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：Count |
| PutRecords.ThrottledRecords | 每個 Kinesis 資料串流之 `PutRecords` 操作中的由於限流遭拒的記錄數目，這是對指定的期間進行測量。 維度：StreamName 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：Count |
| ReadProvisionedThroughputExceeded | 在指定的期間內，針對串流進行調節的 `GetRecords` 呼叫數目。此指標的最常用統計資訊是 Average。 Minimum 統計資訊的值為 1 時，已在指定期間內調節串流的所有記錄。 Maximum 統計資訊的值為 0 (零) 時，未在指定期間內調節串流的任何記錄。 分區層級指標名稱：`ReadProvisionedThroughputExceeded` 維度：StreamName 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：Count |
| SubscribeToShard.RateExceeded | 當新訂閱嘗試因為已有相同消費者的作用中訂閱或您超出此操作每秒允許的呼叫數目而失敗時，會發出此指標。維度：StreamName、ConsumerName |
| SubscribeToShard.Success | 此指標會記錄 SubscribeToShard 訂閱是否已成功建立。訂閱最多只會存留 5 分鐘。因此，此指標至少每 5 分鐘發出一次。 維度：StreamName、ConsumerName |
| SubscribeToShardEvent.Bytes | 接收自碎片的位元組數目，此數量是在指定的期間進行測量。Minimum、Maximum 與 Average 統計資訊代表指定時段內在單一事件中發佈的位元組。 分區層級指標名稱：`OutgoingBytes` 維度：StreamName、ConsumerName 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：位元組 |
| SubscribeToShardEvent.MillisBehindLatest | 讀取記錄來自串流頂端的毫秒數，表示消費者目前時間落後多久。 維度：StreamName、ConsumerName 統計資訊：Minimum、Maximum、Average、Samples 單位：毫秒 |
| SubscribeToShardEvent.Records | 接收自碎片的記錄數目，此數量是在指定的期間進行測量。Minimum、Maximum 與 Average 統計資訊代表指定時段內在單一事件中的記錄。 分區層級指標名稱：`OutgoingRecords` 維度：StreamName、ConsumerName 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：Count |
| SubscribeToShardEvent.Success | 此指標會在每次事件成功發佈時發出。只在有作用中訂閱時此發出此指標。維度：StreamName、ConsumerName統計資訊：Minimum、Maximum、Average、Sum、Samples單位：Count |
| WriteProvisionedThroughputExceeded | 因在指定期間內調節串流而拒絕的記錄數目。此指標包含來自 `PutRecord` 與 `PutRecords` 操作的調節。此指標的最常用統計資訊是 Average。 Minimum 統計資訊的值為非零時，正在指定期間內調節串流的記錄。 Maximum 統計資訊的值為 0 (零) 時，目前未在指定期間內調節串流的所有記錄。 分區層級指標名稱：`WriteProvisionedThroughputExceeded` 維度：StreamName 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：Count |
### 增強的碎片層級指標
`AWS/Kinesis` 命名空間包含下列分區層級指標。
Kinesis 會每分鐘將下列碎片層級指標傳送至 CloudWatch。每個指標維度會建立 1 個 CloudWatch 指標，每個月進行大約 43,200 個 `PutMetricData` API 呼叫。預設不會啟用這些指標。Kinesis 發出之增強型指標會收取費用。如需詳細資訊，請參閱 *Amazon CloudWatch 定價*下的[ Amazon CloudWatch 自訂指標](https://aws.amazon.com/cloudwatch/pricing/)。每個月每個指標的每個分區都會收取費用。
| 指標 | Description |
| --- | --- |
| IncomingBytes | 在指定的期間內，成功放入分區的位元組數目。此指標包含來自 `PutRecord` 與 `PutRecords` 操作的位元組。Minimum、Maximum 與 Average 統計資訊代表指定期間內分區之單一 Put 操作中的位元組。 串流層級指標名稱：`IncomingBytes` 維度：StreamName、ShardId 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：位元組 |
| IncomingRecords | 在指定的期間內，成功放入分區的記錄數目。此指標包含來自 `PutRecord` 與 `PutRecords` 操作的記錄計數。Minimum、Maximum 與 Average 統計資訊代表指定期間內分區之單一 Put 操作中的記錄。 串流層級指標名稱：`IncomingRecords` 維度：StreamName、ShardId 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：Count |
| IteratorAgeMilliseconds | 對分區進行之所有 `GetRecords` 呼叫中最後一筆記錄的存留期，這是對指定的期間進行測量。目前時間與將 `GetRecords` 呼叫的最後一筆記錄寫入至串流時之間的差異就是存留期。Minimum 和 Maximum 統計資訊可以用來追蹤 Kinesis 取用者應用程式進度。0 (零) 值指出所讀取的記錄完全與串流同步。 串流層級指標名稱：`GetRecords.IteratorAgeMilliseconds` 維度：StreamName、ShardId 統計資訊：Minimum、Maximum、Average、Samples 單位：毫秒 |
| OutgoingBytes | 擷取自分區的位元組數目，這是對指定的期間進行測量。Minimum、Maximum 與 Average 統計資訊代表在指定期間內碎片之單一 `GetRecords` 操作中傳回或在單一 `SubscribeToShard` 事件中發佈的位元組。 串流層級指標名稱：`GetRecords.Bytes` 維度：StreamName、ShardId 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：位元組 |
| OutgoingRecords | 擷取自分區的記錄數目，這是對指定的期間進行測量。Minimum、Maximum 與 Average 統計資訊代表在指定期間內碎片之單一 `GetRecords` 操作中傳回或在單一 `SubscribeToShard` 事件中發佈的記錄。 串流層級指標名稱：`GetRecords.Records` 維度：StreamName、ShardId 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：Count |
| ReadProvisionedThroughputExceeded | 在指定的期間內，針對分區進行調節的 `GetRecords` 呼叫數目。這項例外計數涵蓋下列限制的所有維度：每秒每個分區 5 次讀取或每個分區每秒 2 MB。此指標的最常用統計資訊是 Average。 Minimum 統計資訊的值為 1 時，已在指定期間內調節分區的所有記錄。 Maximum 統計資訊的值為 0 (零) 時，未在指定期間內調節分區的任何記錄。 串流層級指標名稱：`ReadProvisionedThroughputExceeded` 維度：StreamName、ShardId 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：Count |
| WriteProvisionedThroughputExceeded | 因在指定期間內調節分區而拒絕的記錄數目。此指標包含來自 `PutRecord` 與 `PutRecords` 操作的調節，並涵蓋下列限制的所有維度：每個分區每秒 1,000 筆記錄或每個分區每秒 1 MB。此指標的最常用統計資訊是 Average。 Minimum 統計資訊的值為非零時，正在指定期間內調節分區的記錄。 Maximum 統計資訊的值為 0 (零) 時，未在指定期間內調節分區的任何記錄。 串流層級指標名稱：`WriteProvisionedThroughputExceeded` 維度：StreamName、ShardId 統計資訊：Minimum、Maximum、Average、Sum、Samples 單位：Count |
### Amazon Kinesis Data Streams 指標的維度
| 維度 | Description |
| --- | --- |
| StreamName | Kinesis 串流名稱。所有可用的統計資訊皆以 `StreamName` 篩選。 |
### 建議的 Amazon Kinesis Data Streams 指標
Kinesis 資料串流客戶可能會對數個 Amazon Kinesis Data Streams 指標會特別感興趣。以下清單提供建議的指標和其使用方式。
| 指標 | 使用須知 |
| --- | --- |
| `GetRecords.IteratorAgeMilliseconds` | 追蹤串流中所有碎片和取用者的讀取位置。如果反覆運算器的存留期超過保留期間的 50% (預設為 24 小時，最多可設定為 7 天)，會有由於記錄過期而遺失資料的風險。建議您對最大統計資料使用 CloudWatch 警示，以在此遺失有風險之前提醒您。如需使用此指標的範例案例，請參閱[消費者記錄處理落後](troubleshooting-consumers.md#record-processing-falls-behind)。 |
| `ReadProvisionedThroughputExceeded` | 當您的取用者端記錄處理落後，有時難以知道瓶頸所在位置。使用此指標來判斷您的讀取是否因為超過讀取輸送量限制而受到節制。此指標的最常用統計資訊是 Average。 |
| WriteProvisionedThroughputExceeded | 這是用於與 ReadProvisionedThroughputExceeded 指標相同的用途，但用於串流的生產程式 (put) 端。此指標的最常用統計資訊是 Average。 |
| PutRecord.Success, PutRecords.Success | 建議在平均統計資料上使用 CloudWatch 警示來指示對串流失敗的記錄。根據生產程式的用途，選擇其中一個或兩個 put 類型。如果使用 Amazon Kinesis Producer Library (KPL)，請使用 PutRecords.Success。 |
| GetRecords.Success | 建議在平均統計資料上使用 CloudWatch 警示來指示自串流失敗之記錄的時間。 |
## 存取 Kinesis Data Streams 的 Amazon CloudWatch 指標
您可以使用 CloudWatch 主控台、命令列或 CloudWatch API 來監控 Kinesis Data Streams 指標。以下程序將說明如何使用這些不同的方法來存取指標。
**使用 CloudWatch 主控台檢視指標**
1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 在導覽列上，選擇一個區域。
1. 在導覽窗格中，選擇 **指標**。
1. 在 **CloudWatch Metrics by Category (依類別的 CloudWatch 指標)** 窗格中，選擇 **Kinesis Metrics (Kinesis 指標)**。
1. 按一下相關資料列來檢視指定 **MetricName** 和 **StreamName** 的統計資料。
**注意：**大多數主控台統計資料名稱符合先前列出的對應 CloudWatch 指標名稱，**但讀取輸送量**和**寫入輸送量**除外。系統會在 5 分鐘的間隔計算這些統計資料：**寫入輸送量**會監控 `IncomingBytes` CloudWatch 指標，**讀取輸送量**會監控 `GetRecords.Bytes`。
1. (選用) 在圖形窗格中，選取統計資料和時段，然後利用這些設定來建立 CloudWatch 警示。
**使用 存取指標 AWS CLI**
使用 [list-metrics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/list-metrics.html) 和 [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) 命令。
**使用 CloudWatch CLI 存取指標**
使用 [mon-list-metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/cli/cli-mon-list-metrics.html) 和 [mon-get-stats](https://docs.aws.amazon.com/AmazonCloudWatch/latest/cli/cli-mon-get-stats.html) 命令。
**使用 CloudWatch API 存取指標**
使用 [ListMetrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_ListMetrics.html) 和 [GetMetricStatistics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetMetricStatistics.html) 操作。
# 使用 Amazon CloudWatch 監控 Kinesis Data Streams Agent 運作狀態
代理程式會使用 **AWS KinesisAgent** 命名空間來發布自訂 CloudWatch 指標。這些指標可幫助您評估代理程式是否如指定將資料提交至 Kinesis Data Streams，以及它是否正常運作並在資料產生來源上耗用適當數量的 CPU 和記憶體資源。例如傳送的記錄數量和位元組等指標，有助於了解客服人員將資料提交至串流的速率。當這些指標滑落至預期閾值以下特定百分比或滑落至零，可能表示設定有問題、網路出現錯誤或代理程式運作狀態不佳。諸如主機 CPU 和記憶體的消耗量與代理程式錯誤計數器等指標，均顯示資料產生來源的資源使用情況，並提供潛在的設定或主機錯誤等洞見。最後，代理程式亦會記錄服務例外狀況，以協助調查代理程式的問題。這些指標會在代理程式組態設定 `cloudwatch.endpoint` 中指定的區域中回報。從多個 Kinesis 代理程式發佈的 CloudWatch 指標會彙總或合併。如需代理程式組態的詳細資訊，請參閱[指定代理程式組態設定](writing-with-agents.md#agent-config-settings)。
## 使用 CloudWatch 監控
Kinesis Data Streams 代理程式會向 CloudWatch 傳送下列指標。
| 指標 | Description |
| --- | --- |
| BytesSent | 在指定期間內，傳送至 Kinesis Data Streams 的位元組數目。 單位：位元組 |
| RecordSendAttempts | 呼叫於指定期間內`PutRecords`嘗試的記錄 (不論第一次嘗試或是重試) 數量。 單位：Count |
| RecordSendErrors | 呼叫於指定期間內`PutRecords`回傳失敗狀態的記錄 (包括重試) 數量。 單位：Count |
| ServiceErrors | 呼叫於指定期間內`PutRecords`導致服務錯誤 (調節錯誤除外) 數量。 單位：Count |
# 使用 記錄 Amazon Kinesis Data Streams API 呼叫 AWS CloudTrail
Amazon Kinesis Data Streams 已與 服務整合 AWS CloudTrail，此服務提供由使用者、角色或 Kinesis Data Streams 中的 AWS 服務所採取之動作的記錄。CloudTrail 會將 Kinesis Data Streams 的所有 API 呼叫擷取為事件。擷取的呼叫包括來自 Amazon Kinesis Video Streams 主控台的呼叫，以及程式碼對 Kinesis Data Streams API 操作的呼叫。如果您建立線索，就可以持續將 CloudTrail 事件交付至 Amazon S3 儲存貯體，包括 Kinesis Data Streams 的事件。即使您未設定追蹤，依然可以透過 CloudTrail 主控台中的**事件歷史記錄**檢視最新事件。您可以利用 CloudTrail 所收集的資訊來判斷向 Kinesis Data Streams 發出的請求，以及發出請求的 IP 地址、人員、時間和其他詳細資訊。
若要進一步了解 CloudTrail，包括如何設定及啟用，請參閱[《AWS CloudTrail 使用者指南》](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)。
## CloudTrail 中的 Kinesis Data Streams 資訊
當您建立 AWS 帳戶時，會在您的帳戶上啟用 CloudTrail。當 Kinesis Data Streams 中發生支援的事件活動時，該活動會與**事件歷史記錄**中的其他 AWS 服務事件一起記錄在 CloudTrail 事件中。您可以在 AWS 帳戶中檢視、搜尋和下載最近的事件。如需詳細資訊，請參閱《使用 CloudTrail 事件歷史記錄檢視事件》[https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html)。
若要持續記錄您 AWS 帳戶中的事件，包括 Kinesis Data Streams 的事件，請建立追蹤。*線索*能讓 CloudTrail 將日誌檔案交付至 Amazon S3 儲存貯體。根據預設，當您在主控台中建立線索時，線索會套用至所有 AWS 區域。線索會記錄 AWS 分割區中所有區域的事件，並將日誌檔案傳送到您指定的 Amazon S3 儲存貯體。此外，您可以設定其他 AWS 服務，以進一步分析和處理 CloudTrail 日誌中所收集的事件資料。如需詳細資訊，請參閱下列內容：
+ [建立追蹤的概觀](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)
+ [CloudTrail 支援的服務和整合](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations)
+ [設定 CloudTrail 的 Amazon SNS 通知](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html)
+ [從多個區域接收 CloudTrail 日誌檔案](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html)，以及[從多個帳戶接收 CloudTrail 日誌檔案](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html)
Kinesis Data Streams 支援將下列 API 動作記錄為 CloudTrail 日誌檔案中的事件：
+ [AddTagsToStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_AddTagsToStream.html)
+ [CreateStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_CreateStream.html)
+ [DecreaseStreamRetentionPeriod](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_DecreaseStreamRetentionPeriod.html)
+ [DeleteStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_DeleteStream.html)
+ [DeregisterStreamConsumer](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_DeregisterStreamConsumer.html)
+ [DescribeStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_DescribeStream.html)
+ [DescribeStreamConsumer](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_DescribeStreamConsumer.html)
+ [DisableEnhancedMonitoring](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_DisableEnhancedMonitoring.html)
+ [EnableEnhancedMonitoring](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_EnableEnhancedMonitoring.html)
+ [GetRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetRecords.html)
+ [GetShardIterator](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetShardIterator.html)
+ [IncreaseStreamRetentionPeriod](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_IncreaseStreamRetentionPeriod.html)
+ [ListStreamConsumers](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_ListStreamConsumers.html)
+ [ListStreams](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_ListStreams.html)
+ [ListTagsForStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_ListTagsForStream.html)
+ [MergeShards](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_MergeShards.html)
+ [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html)
+ [PutRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecords.html)
+ [RegisterStreamConsumer](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_RegisterStreamConsumer.html)
+ [RemoveTagsFromStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_RemoveTagsFromStream.html)
+ [SplitShard](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_SplitShard.html)
+ [StartStreamEncryption](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_StartStreamEncryption.html)
+ [StopStreamEncryption](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_StopStreamEncryption.html)
+ [SubscribeToShard](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_SubscribeToShard.html)
+ [UpdateShardCount](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_UpdateShardCount.html)
+ [UpdateStreamMode](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_UpdateStreamMode.html)
每一筆事件或日誌專案都會包含產生請求者的資訊。身分資訊可協助您判斷下列事項：
+ 是否使用根或 AWS Identity and Access Management (IAM) 使用者登入資料提出請求。
+ 提出該請求時，是否使用了特定角色或聯合身分使用者的暫時安全憑證。
+ 請求是否由其他 AWS 服務提出。
如需詳細資訊，請參閱 [CloudTrail userIdentity 元素](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)。
## 範例：Kinesis Data Streams 日誌檔案項目
追蹤是一種組態，能讓事件以日誌檔案的形式交付到您指定的 Amazon S3 儲存貯體。CloudTrail 日誌檔案包含一或多個日誌專案。一個事件為任何來源提出的單一請求，並包含請求動作、請求的日期和時間、請求參數等資訊。CloudTrail 日誌檔並非依公有 API 呼叫的堆疊追蹤排序，因此不會以任何特定順序出現。
以下範例顯示的是展示 `CreateStream`、`DescribeStream`、`ListStreams`、`DeleteStream`、`SplitShard` 及 `MergeShards` 動作的 CloudTrail 日誌項目。
```
{
"Records": [
{
"eventVersion": "1.01",
"userIdentity": {
"type": "IAMUser",
"principalId": "EX_PRINCIPAL_ID",
"arn": "arn:aws:iam::012345678910:user/Alice",
"accountId": "012345678910",
"accessKeyId": "EXAMPLE_KEY_ID",
"userName": "Alice"
},
"eventTime": "2014-04-19T00:16:31Z",
"eventSource": "kinesis.amazonaws.com",
"eventName": "CreateStream",
"awsRegion": "us-east-1",
"sourceIPAddress": "127.0.0.1",
"userAgent": "aws-sdk-java/unknown-version Linux/x.xx",
"requestParameters": {
"shardCount": 1,
"streamName": "GoodStream"
},
"responseElements": null,
"requestID": "db6c59f8-c757-11e3-bc3b-57923b443c1c",
"eventID": "b7acfcd0-6ca9-4ee1-a3d7-c4e8d420d99b"
},
{
"eventVersion": "1.01",
"userIdentity": {
"type": "IAMUser",
"principalId": "EX_PRINCIPAL_ID",
"arn": "arn:aws:iam::012345678910:user/Alice",
"accountId": "012345678910",
"accessKeyId": "EXAMPLE_KEY_ID",
"userName": "Alice"
},
"eventTime": "2014-04-19T00:17:06Z",
"eventSource": "kinesis.amazonaws.com",
"eventName": "DescribeStream",
"awsRegion": "us-east-1",
"sourceIPAddress": "127.0.0.1",
"userAgent": "aws-sdk-java/unknown-version Linux/x.xx",
"requestParameters": {
"streamName": "GoodStream"
},
"responseElements": null,
"requestID": "f0944d86-c757-11e3-b4ae-25654b1d3136",
"eventID": "0b2f1396-88af-4561-b16f-398f8eaea596"
},
{
"eventVersion": "1.01",
"userIdentity": {
"type": "IAMUser",
"principalId": "EX_PRINCIPAL_ID",
"arn": "arn:aws:iam::012345678910:user/Alice",
"accountId": "012345678910",
"accessKeyId": "EXAMPLE_KEY_ID",
"userName": "Alice"
},
"eventTime": "2014-04-19T00:15:02Z",
"eventSource": "kinesis.amazonaws.com",
"eventName": "ListStreams",
"awsRegion": "us-east-1",
"sourceIPAddress": "127.0.0.1",
"userAgent": "aws-sdk-java/unknown-version Linux/x.xx",
"requestParameters": {
"limit": 10
},
"responseElements": null,
"requestID": "a68541ca-c757-11e3-901b-cbcfe5b3677a",
"eventID": "22a5fb8f-4e61-4bee-a8ad-3b72046b4c4d"
},
{
"eventVersion": "1.01",
"userIdentity": {
"type": "IAMUser",
"principalId": "EX_PRINCIPAL_ID",
"arn": "arn:aws:iam::012345678910:user/Alice",
"accountId": "012345678910",
"accessKeyId": "EXAMPLE_KEY_ID",
"userName": "Alice"
},
"eventTime": "2014-04-19T00:17:07Z",
"eventSource": "kinesis.amazonaws.com",
"eventName": "DeleteStream",
"awsRegion": "us-east-1",
"sourceIPAddress": "127.0.0.1",
"userAgent": "aws-sdk-java/unknown-version Linux/x.xx",
"requestParameters": {
"streamName": "GoodStream"
},
"responseElements": null,
"requestID": "f10cd97c-c757-11e3-901b-cbcfe5b3677a",
"eventID": "607e7217-311a-4a08-a904-ec02944596dd"
},
{
"eventVersion": "1.01",
"userIdentity": {
"type": "IAMUser",
"principalId": "EX_PRINCIPAL_ID",
"arn": "arn:aws:iam::012345678910:user/Alice",
"accountId": "012345678910",
"accessKeyId": "EXAMPLE_KEY_ID",
"userName": "Alice"
},
"eventTime": "2014-04-19T00:15:03Z",
"eventSource": "kinesis.amazonaws.com",
"eventName": "SplitShard",
"awsRegion": "us-east-1",
"sourceIPAddress": "127.0.0.1",
"userAgent": "aws-sdk-java/unknown-version Linux/x.xx",
"requestParameters": {
"shardToSplit": "shardId-000000000000",
"streamName": "GoodStream",
"newStartingHashKey": "11111111"
},
"responseElements": null,
"requestID": "a6e6e9cd-c757-11e3-901b-cbcfe5b3677a",
"eventID": "dcd2126f-c8d2-4186-b32a-192dd48d7e33"
},
{
"eventVersion": "1.01",
"userIdentity": {
"type": "IAMUser",
"principalId": "EX_PRINCIPAL_ID",
"arn": "arn:aws:iam::012345678910:user/Alice",
"accountId": "012345678910",
"accessKeyId": "EXAMPLE_KEY_ID",
"userName": "Alice"
},
"eventTime": "2014-04-19T00:16:56Z",
"eventSource": "kinesis.amazonaws.com",
"eventName": "MergeShards",
"awsRegion": "us-east-1",
"sourceIPAddress": "127.0.0.1",
"userAgent": "aws-sdk-java/unknown-version Linux/x.xx",
"requestParameters": {
"streamName": "GoodStream",
"adjacentShardToMerge": "shardId-000000000002",
"shardToMerge": "shardId-000000000001"
},
"responseElements": null,
"requestID": "e9f9c8eb-c757-11e3-bf1d-6948db3cd570",
"eventID": "77cf0d06-ce90-42da-9576-71986fec411f"
}
]
}
```
# 使用 Amazon CloudWatch 監控 Kinesis 用戶端程式庫
適用於 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)
## 指標和命名空間
用來上傳指標的命名空間是當您啟動 KCL 時指定的應用程式名稱。
## 指標層級和維度
有兩種選項可控制上傳到 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 工作者間必須是唯一的。
## 指標組態
指標層級和啟用的維度可以使用 KinesisClientLibConfiguration 執行個體加以設定，會在啟動 KCL 應用程式時將該執行個體傳送至工作者。在 MultiLangDaemon 情況下，您可以在 .properties 檔案中指定用於啟動 MultiLangDaemon KCL 應用程式的 `metricsLevel` 和 `metricsEnabledDimensions` 屬性。
您可以對指標層級指派下列三個值中的其中之一：NONE、SUMMARY 或 DETAILED。啟用的維度值必須是對 CloudWatch 指標允許之維度以逗號分隔字串的清單。KCL 應用程式使用的維度為 `Operation`、`ShardId` 及 `WorkerIdentifier`。
## 指標清單
下表列出 KCL 指標，依範圍和操作分組。
**Topics**
+ [Per-KCL-application指標](#kcl-metrics-per-app)
+ [每個工作者的指標](#kcl-metrics-per-worker)
+ [每個碎片指標](#kcl-metrics-per-shard)
### Per-KCL-application指標
這些指標會在應用程式範圍內的所有 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
`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
`InitializeTask` 操作負責初始化 KCL 應用程式的記錄處理器。此操作的邏輯包含取得來自 Kinesis Data Streams 的碎片反覆運算器和初始化記錄處理器。
| 指標 | Description |
| --- | --- |
| KinesisDataFetcher.getIterator.Success | 每一 KCL 應用程式成功 `GetShardIterator` 操作的數量。 指標層級：詳細 單位：Count |
| KinesisDataFetcher.getIterator.Time | 指定 KCL 應用程式的每個 `GetShardIterator` 操作耗費的時間。 指標層級：詳細 單位：毫秒 |
| RecordProcessor.initialize.Time | 記錄處理器的 initialize 方法耗費的時間。 指標層級：摘要 單位：毫秒 |
| 成功 | 成功的記錄處理器初始化的數量。 指標層級：摘要 單位：Count |
| 時間 | KCL 工作者的記錄處理器初始化耗費的時間。 指標層級：摘要 單位：毫秒 |
#### ShutdownTask
`ShutdownTask` 操作會初始化碎片處理的關閉序列。因為碎片分割或合併，或當工作者遺失碎片租用時可能會發生此情況。在這兩種情況下，會叫用記錄處理器 `shutdown()` 函數。當碎片分割或合併造成建立一或兩個新的碎片的情況下，也會發現新的碎片。
| 指標 | Description |
| --- | --- |
| CreateLease.Success | 在父碎片關閉之後將新子碎片成功新增到 KCL 應用程式 DynamoDB 資料表的次數。 指標層級：詳細 單位：Count |
| CreateLease.Time | 在 KCL 應用程式 DynamoDB 資料表中新增子碎片資訊耗費的時間。 指標層級：詳細 單位：毫秒 |
| UpdateLease.Success | 記錄處理器關閉期間成功的最終檢查點數量。 指標層級：詳細 單位：Count |
| UpdateLease.Time | 記錄處理器關閉期間檢查點操作耗費的時間。 指標層級：詳細 單位：毫秒 |
| RecordProcessor.shutdown.Time | 記錄處理器的 shutdown 方法耗費的時間。 指標層級：摘要 單位：毫秒 |
| 成功 | 成功關閉任務的數量。 指標層級：摘要 單位：Count |
| 時間 | KCL 工作者的關閉任務耗費的時間。 指標層級：摘要 單位：毫秒 |
#### ShardSyncTask
`ShardSyncTask` 操作會探索對 Kinesis 資料串流碎片資訊的變更，使得 KCL 應用程式可以處理新的碎片。
| 指標 | Description |
| --- | --- |
| CreateLease.Success | 成功嘗試將新的碎片資訊新增至 KCL 應用程式 DynamoDB 資料表的數量。 指標層級：詳細 單位：Count |
| CreateLease.Time | 在 KCL 應用程式 DynamoDB 資料表中新增碎片資訊耗費的時間。 指標層級：詳細 單位：毫秒 |
| 成功 | 成功的碎片同步操作數量。 指標層級：摘要 單位：Count |
| 時間 | 碎片同步操作耗費的時間。 指標層級：摘要 單位：毫秒 |
#### BlockOnParentTask
如果碎片分割或與其他碎片合併，則會建立新的子碎片。`BlockOnParentTask` 操作可確保新碎片的記錄處理不會開始，直到 KCL 已完全處理父碎片為止。
| 指標 | Description |
| --- | --- |
| 成功 | 成功的父碎片完成檢查數量。 指標層級：摘要 單位：Count |
| 時間 | 父碎片完成耗費的時間。 指標層級：摘要 單位：毫秒 |
#### PeriodicShardSyncManager
`PeriodicShardSyncManager` 負責檢查 KCL 取用者應用程式正在處理的資料串流，識別具有部分租用的資料串流，並將其移交以進行同步處理。
當 KCL 設定為處理單一資料串流 (然後將 NumStreamStoSync 和 NumStreamsWithPartialLeases 設定為 1)，以及將 KCL 設定為處理多個資料串流時，可以使用下列指標。
| 指標 | Description |
| --- | --- |
| NumStreamsToSync | 消費者應用程式處理的資料串流數目 （每個 AWS 帳戶），其中包含部分租用且必須遞交以進行同步處理。 指標層級：摘要 單位：Count |
| NumStreamsWithPartialLeases | 消費者應用程式正在處理的資料串流數目 （每個 AWS 帳戶），其中包含部分租用。 指標層級：摘要 單位：Count |
| 成功 | `PeriodicShardSyncManager` 能夠在取用者應用程式正在處理的資料串流中成功識別部分租用的次數。 指標層級：摘要 單位：Count |
| 時間 | 檢查取用者應用程式正在處理的資料串流`PeriodicShardSyncManager`所需的時間量 （以毫秒為單位），以判斷哪些資料串流需要碎片同步處理。 指標層級：摘要 單位：毫秒 |
#### MultistreamTracker
此 `MultistreamTracker` 介面可讓您建置可同時處理多個資料串流的 KCL 取用者應用程式。
| 指標 | Description |
| --- | --- |
| DeletedStreams.Count | 在此期間刪除的資料串流數目。 指標層級：摘要 單位：Count |
| ActiveStreams.Count | 正在處理的作用中資料串流數目。 指標層級：摘要 單位：Count |
| StreamsPendingDeletion.Count | 擱置刪除的資料串流數目 (依據 `FormerStreamsLeasesDeletionStrategy`)。 指標層級：摘要 單位：Count |
### 每個工作者的指標
系統會針對耗用來自 Kinesis 資料串流 (例如：Amazon EC2 執行個體) 之資料的所有記錄處理器彙總這些指標。
**Topics**
+ [WorkerMetricStatsReporter](#worker-metrics-stats)
+ [LeaseDiscovery](#lease-discovery)
+ [RenewAllLeases](#renew-leases)
+ [TakeLeases](#take-leases)
#### WorkerMetricStatsReporter
`WorkerMetricStatReporter` 操作負責定期將目前工作者的指標發佈至工作者指標表。`LeaseAssignmentManager` 操作使用這些指標來執行租用指派。
| 指標 | Description |
| --- | --- |
| InMemoryMetricStatsReporterFailure | 由於某些工作者指標失敗，擷取記憶體內工作者指標值的失敗次數。 指標層級：摘要 單位：Count |
| WorkerMetricStatsReporter.Time | `WorkerMetricsStats` 操作所花費的時間。 指標層級：摘要 單位：毫秒 |
| WorkerMetricStatsReporter.Success | 成功完成 `WorkerMetricsStats` 操作的次數。 指標層級：摘要 單位：Count |
#### LeaseDiscovery
`LeaseDiscovery` 操作負責識別操作指派給目前工作者的新租用`LeaseAssignmentManager`。此操作的邏輯涉及透過讀取租用資料表的全域次要索引來識別指派給目前工作者的租用。
| 指標 | Description |
| --- | --- |
| ListLeaseKeysForWorker.Time | 呼叫租用資料表上的全域次要索引，並取得指派給目前工作者的租用金鑰的時間。 指標層級：詳細 單位：毫秒 |
| FetchNewLeases.Time | 從租用資料表擷取所有新租用的時間。 指標層級：詳細 單位：毫秒 |
| NewLeasesDiscovered | 指派給工作者的新租用總數。 指標層級：詳細 單位：Count |
| 時間 | `LeaseDiscovery` 操作所花費的時間。 指標層級：摘要 單位：毫秒 |
| 成功 | 成功完成 `LeaseDiscovery` 操作的次數。 指標層級：摘要 單位：Count |
| OwnerMismatch | 來自 GSI 回應和租用資料表一致讀取的擁有者不相符數量。 指標層級：詳細 單位：Count |
#### RenewAllLeases
`RenewAllLeases` 操作會定期更新特定工作者執行個體擁有的碎片租用。
| 指標 | Description |
| --- | --- |
| RenewLease.Success | 成功的工作者租用更新數量。 指標層級：詳細 單位：Count |
| RenewLease.Time | 租用更新操作耗費的時間。 指標層級：詳細 單位：毫秒 |
| CurrentLeases | 在更新所有租用之後，工作者擁有的碎片租用數量。 指標層級：摘要 單位：Count |
| LostLeases | 嘗試更新工作者擁有的所有租用之後，遺失的碎片租用數量。 指標層級：摘要 單位：Count |
| 成功 | 工作者的租用續約操作成功次數。 指標層級：摘要 單位：Count |
| 時間 | 更新工作者所有租用耗費的時間。 指標層級：摘要 單位：毫秒 |
#### TakeLeases
`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` 操作耗費的時間。 指標層級：摘要 單位：毫秒 |
### 每個碎片指標
系統會對單一記錄處理器彙總這些指標。
#### ProcessTask
`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 |
| 時間 | 處理任務操作耗費的時間。 指標層級：摘要 單位：毫秒 |
# 使用 Amazon CloudWatch 監控 Kinesis Producer Library
[Amazon Kinesis Data Streams 的 Amazon Kinesis Producer Library](https://docs.aws.amazon.com/kinesis/latest/dev/developing-producers-with-kpl.html) (KPL) 會代表您發佈自訂 Amazon CloudWatch 指標。 Amazon Kinesis 然後，您可以導覽至 [CloudWatch 主控台](https://console.aws.amazon.com/cloudwatch/)，並選擇**自訂指標**來檢視這些指標。如需詳細資訊，請參閱《Amazon CloudWatch 使用者指南》**中的[發佈自訂指標](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/publishingMetrics.html)。
這是 KPL 將指標上傳到 CloudWatch 的名目費用；具體而言，適用 Amazon CloudWatch 自訂指標和 Amazon CloudWatch API 請求費用。如需詳細資訊，請參閱 [Amazon CloudWatch 定價](https://aws.amazon.com/cloudwatch/pricing/)。蒐集本機指標不會產生 CloudWatch 費用。
**Topics**
+ [指標、維度和命名空間](#kpl-metrics)
+ [指標層級和精細程度](#kpl-metrics-granularity)
+ [本機存取和 Amazon CloudWatch 上傳](#kpl-metrics-local-upload)
+ [指標清單](#kpl-metrics-list)
## 指標、維度和命名空間
啟動 KPL 時您可以指定應用程式名稱，然後在上傳指標時使用它做為命名空間的一部分。這是選用的；如果未設定應用程式名稱，KPL 會提供預設值。
您也可以設定 KPL 以將任意的其他維度新增到指標。如果您需要在 CloudWatch 指標中有更精確的資料，此功能會很有用。例如，您可以將主機名稱新增為維度，即可讓您識別機群中不平均的負載分配。所有 KPL 組態設定是不變的，因此在初始化 KPL 執行個體之後，您無法變更這些額外的維度。
## 指標層級和精細程度
有兩種選項可控制上傳到 CloudWatch 的指標數量：
*指標層級*
這是指標重要性的約略判斷方法。每個指標會獲指派層級。設定層級時，低於該層級的指標不會傳送到 CloudWatch。層級為 `NONE`、`SUMMARY` 和 `DETAILED`。預設設定為 `DETAILED`；也就是說，所有指標 `NONE` 表示完全不須指標，因此不會將任何指標指派至該層級。
*精細程度*
此選項可控制是否以額外的精細程度層級發出相同的指標。層級為 `GLOBAL`、`STREAM` 和 `SHARD`。預設設定為 `SHARD`，其包含最精細的指標。
選擇 `SHARD` 時，會以串流名稱和碎片 ID 做為維度發出指標。此外，也會僅以串流名稱維度，以及沒有串流名稱的指標發出相同的指標。這表示，對於特定指標，兩個串流 (其中每個串流擁有兩個碎片) 將產生 7 個 CloudWatch 指標：每個碎片一個、每個串流一個，以及一個整體；都描述相同的統計資料，但在不同層級的精細程度。如需圖解，請參閱以下圖表。
不同精細程度層級形成階層，而系統中的所有指標形成樹狀目錄，根目錄為指標名稱：
```
MetricName (GLOBAL): Metric X Metric Y
| |
----------------- ------------
| | | |
StreamName (STREAM): Stream A Stream B Stream A Stream B
| |
-------- ---------
| | | |
ShardID (SHARD): Shard 0 Shard 1 Shard 0 Shard 1
```
並非所有指標都可在碎片層級取得；而部分指標的本質為串流層級或全域。即使您已啟用碎片層級指標 (前述圖表中的 `Metric Y`)，也不會在碎片層級產生這些指標。
當您指定額外的維度時，必須提供 的值`tuple:`。精細程序用來決定在階層中插入自訂維度的位置：`GLOBAL` 表示在指標名稱後插入額外的維度，`STREAM` 表示在串流名稱之後插入，和 `SHARD` 表示在碎片 ID 之後插入。如果為每個精細程序層級提供多個額外的維度，則會以指定的順序插入。
## 本機存取和 Amazon CloudWatch 上傳
目前 KPL 執行個體的指標可即時在本機取得；您可以隨時查詢 KPL 來取得這些指標。KPL 會在本機計算每個指標的總和、平均、最小值、最大值和計數，如同在 CloudWatch 一般。
您可以取得從計畫開始累計到目前時間點的統計資料，或使用過去 *N* 秒的滾動時段，其中 *N* 為 1 到 60 之間的整數。
所有指標可供上傳至 CloudWatch。這非常適合用於彙總跨多個主機、監控和警示的資料。此功能無法在本機使用。
如前所述，您可以選取要使用*指標層級*和*精細程度*設定來上傳的指標。未上傳的指標可在本機取得。
個別上傳資料點不可行，因為如果流量很高，它可能產生每秒數百萬個上傳。因此，KPL 會在本機將指標彙總為 1 分鐘的儲存貯體，並對每個啟用的指標每分鐘一次將統計資料物件上傳至 CloudWatch。
## 指標清單
| 指標 | Description |
| --- | --- |
| UserRecordsReceived | KPL 核心針對 put 操作所收到多少個邏輯使用者記錄的計數。碎片層級不適用。 指標層級：詳細 單位：計數 |
| UserRecordsPending | 目前待處理的有多少個使用者記錄的定期取樣。如果記錄目前處於緩衝狀態並等待傳送，或正在傳送和傳輸到後端服務，則該記錄會處於待定狀態。碎片層級不適用。 KPL 提供一個專用的方法，可在全域層級擷取此指標，讓客戶管理其 put 速率。 指標層級：詳細 單位：計數 |
| UserRecordsPut | 已成功 put 多少個邏輯使用者記錄的計數。 KPL 會對失敗的記錄輸出零。這可讓平均提供成功率，讓計數提供嘗試總計，以及讓計數與總和之間的差異提供失敗計數。 指標層級：摘要 單位：計數 |
| UserRecordsDataPut | 邏輯使用者記錄中成功 put 的位元組數。 指標層級：詳細 單位：位元組 |
| KinesisRecordsPut | 成功 put 的 Kinesis Data Streams 記錄的計數 (每個 Kinesis Data Streams 記錄可能包含多個使用者記錄)。 KPL 會對失敗的記錄輸出零。這可讓平均提供成功率，讓計數提供嘗試總計，以及讓計數與總和之間的差異提供失敗計數。 指標層級：摘要 單位：計數 |
| KinesisRecordsDataPut | Kinesis Data Streams 記錄中的位元組。 指標層級：詳細 單位：位元組 |
| ErrorsByCode | 每個錯誤碼類型的計數。這會在一般維度 (例如 `ErrorCode` 和 `StreamName`) 之外產生額外的 `ShardId` 維度。並非每個錯誤都能追蹤至碎片。不能追蹤的錯誤只能在串流或全域層級發出。此指標會擷取限流、碎片對應變更、內部失敗、服務無法使用、逾時等等之類的相關資訊。 Kinesis Data Streams API 錯誤會在每筆 Kinesis Data Streams 記錄中計算一次。Kinesis Data Streams 記錄內的多個使用者記錄不會產生多個計數。 指標層級：摘要 單位：計數 |
| AllErrors | 這是由與**依程式碼的錯誤**之相同錯誤所觸發，但不會區分類型。這很實用，因為錯誤率的一般監控不需要來自所有不同錯誤類型計數的手動總和。 指標層級：摘要 單位：計數 |
| RetriesPerRecord | 每個使用者記錄執行的重試次數。對一次嘗試便成功的記錄會發出零。 資料會在使用者記錄完成 (可能是成功或可能不再可重試) 時發出。如果記錄存活期的值很大，此指標可能會大幅延遲。 指標層級：詳細 單位：計數 |
| BufferingTime | 使用者記錄抵達 KPL 和前往後端之間的時間。會依每個記錄為基礎將此資訊傳輸回使用者，但也會提供做為彙總的統計資料。 指標層級：摘要 單位：毫秒 |
| Request Time | 執行 `PutRecordsRequests` 所耗費的時間。 指標層級：詳細 單位：毫秒 |
| User Records per Kinesis Record | 彙總至單一 Kinesis Data Streams 記錄的邏輯使用者記錄數量。 指標層級：詳細 單位：計數 |
| Amazon Kinesis Records per PutRecordsRequest | 彙總至單一 `PutRecordsRequest` 的 Kinesis Data Streams 記錄數量。碎片層級不適用。 指標層級：詳細 單位：計數 |
| User Records per PutRecordsRequest | `PutRecordsRequest` 內包含之使用者記錄的總數。這大約等同於之前兩個指標的乘積。碎片層級不適用。 指標層級：詳細 單位：計數 |