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

# 使用 Amazon CloudWatch 監控 Kinesis Producer Library
<a name="monitoring-with-kpl"></a>

[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)

## 指標、維度和命名空間
<a name="kpl-metrics"></a>

啟動 KPL 時您可以指定應用程式名稱，然後在上傳指標時使用它做為命名空間的一部分。這是選用的；如果未設定應用程式名稱，KPL 會提供預設值。

您也可以設定 KPL 以將任意的其他維度新增到指標。如果您需要在 CloudWatch 指標中有更精確的資料，此功能會很有用。例如，您可以將主機名稱新增為維度，即可讓您識別機群中不平均的負載分配。所有 KPL 組態設定是不變的，因此在初始化 KPL 執行個體之後，您無法變更這些額外的維度。

## 指標層級和精細程度
<a name="kpl-metrics-granularity"></a>

有兩種選項可控制上傳到 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:<DimensionName, DimensionValue, Granularity>`。精細程序用來決定在階層中插入自訂維度的位置：`GLOBAL` 表示在指標名稱後插入額外的維度，`STREAM` 表示在串流名稱之後插入，和 `SHARD` 表示在碎片 ID 之後插入。如果為每個精細程序層級提供多個額外的維度，則會以指定的順序插入。

## 本機存取和 Amazon CloudWatch 上傳
<a name="kpl-metrics-local-upload"></a>

目前 KPL 執行個體的指標可即時在本機取得；您可以隨時查詢 KPL 來取得這些指標。KPL 會在本機計算每個指標的總和、平均、最小值、最大值和計數，如同在 CloudWatch 一般。

您可以取得從計畫開始累計到目前時間點的統計資料，或使用過去 *N* 秒的滾動時段，其中 *N* 為 1 到 60 之間的整數。

所有指標可供上傳至 CloudWatch。這非常適合用於彙總跨多個主機、監控和警示的資料。此功能無法在本機使用。

如前所述，您可以選取要使用*指標層級*和*精細程度*設定來上傳的指標。未上傳的指標可在本機取得。

個別上傳資料點不可行，因為如果流量很高，它可能產生每秒數百萬個上傳。因此，KPL 會在本機將指標彙總為 1 分鐘的儲存貯體，並對每個啟用的指標每分鐘一次將統計資料物件上傳至 CloudWatch。



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


| 指標 | 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` 內包含之使用者記錄的總數。這大約等同於之前兩個指標的乘積。碎片層級不適用。 指標層級：詳細  單位：計數   |