本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用亚马逊监控 Kinesis 客户端库 CloudWatch
<a name="monitoring-with-kcl"></a>

适用于 Amazon K [inesis Data Streams 的 Kinesis 客户端库](https://docs.aws.amazon.com/kinesis/latest/dev/developing-consumers-with-kcl.html) (KCL) 使用您的 KCL 应用程序的名称作为命名空间，代表您发布自定义的 CloudWatch 亚马逊指标。您可以通过导航到[CloudWatch 控制台](https://console.aws.amazon.com/cloudwatch/)并选择 “**自定义指标” 来查看这些指标**。有关自定义指标的更多信息，请参阅 *Amazon CloudWatch 用户指南*中的[发布自定义指标](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/publishingMetrics.html)。

KCL 上传到 CloudWatch 的指标收取象征性费用；具体而言，*亚马逊 CloudWatch 自定义指标和亚马逊 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`、`ShardId`、`StreamId` 和 `WorkerIdentifier`）。此外，在 KCL 2.x 中，如果将 KCL 配置为处理多个数据流，则无法禁用 `Operation` 和 `StreamId` 维度。`StreamId` 维度仅对 per-shard 指标有效。  
 在 KCL 1.x 中，默认只启用 `Operation` 和 `ShardId` 维度，而 `WorkerIdentifier` 维度会被禁用。在 KCL 1.x 中，无法禁用 `Operation` 维度。  
有关 CloudWatch 指标维度的更多信息，请参阅《亚马逊* CloudWatch 用户指南*》中 “亚马逊 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 应用程序时会传递给 Worker。 MultiLangDaemon 在这种情况下，可以在用于启动 MultiLangDaemon KCL 应用程序的.properties 文件中指定`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)
+ [Per-worker 指标](#kcl-metrics-per-worker)
+ [Per-shard 指标](#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` 操作负责向工作程序分配租约，并重新平衡工作程序之间的租约，以实现工作程序资源的均匀利用。此操作的逻辑包括从租约表中读取租约相关元数据，以及从工作程序指标表中读取指标，并执行租约分配。


| 指标 | 说明 | 
| --- | --- | 
|  LeaseAndWorkerMetricsLoad.Time  |  指在租约分配管理器（LAM）中加载所有租约和工作程序指标条目所花费的时间，LAM 是 KCL 3.x 中引入的新租约分配和负载均衡算法。 指标级别：详细 单位：毫秒  | 
| TotalLeases |  当前 KCL 应用程序的租约总数。 指标级别：汇总 单位：计数  | 
| NumWorkers |  当前 KCL 应用程序中的工作程序总数。 指标级别：汇总 单位：计数  | 
|  AssignExpiredOrUnassignedLeases.Time  |  指在内存中对过期租约进行分配的时间。 指标级别：详细 单位：毫秒  | 
| LeaseSpillover |  指由于达到每个工作程序的最大租约数或最大吞吐量限制而未分配的租约数。 指标级别：汇总 单位：计数  | 
|  BalanceWorkerVariance.Time  |  指在内存中进行工作程序之间租约平衡的时间。 指标级别：详细 单位：毫秒  | 
|  NumOfLeasesReassignment  |  指在当前重新分配迭代中重新分配的租约总数。 指标级别：汇总 单位：计数  | 
|  FailedAssignmentCount  |   AssignLease 调用 DynamoDB 租用表时失败的次数。 指标级别：详细 单位：计数  | 
|  ParallelyAssignLeases.Time  |  指向 DynamoDB 租约表刷新分配的时间。 指标级别：详细 单位：毫秒  | 
|  ParallelyAssignLeases. 成功  |  指成功刷新分配的次数。 指标级别：详细 单位：计数  | 
|  TotalStaleWorkerMetricsEntry  |  指必须清理的工作程序指标条目总数。 指标级别：详细 单位：计数  | 
| StaleWorkerMetricsCleanup.Time |  指从 DynamoDB 工作程序指标表中删除工作程序指标条目的时间。 指标级别：详细 单位：毫秒  | 
| 时间 |  `LeaseAssignmentManager` 操作花费的时间。 指标级别：汇总 单位：毫秒  | 
| 成功 |  `LeaseAssignmentManager` 操作已成功完成的次数。 指标级别：汇总 单位：计数  | 
| ForceLeaderRelease |  表示租约分配管理器已连续 3 次失败，且领导工作程序正在卸除领导权。 指标级别：汇总 单位：计数  | 
|  NumWorkersWithInvalidEntry  |  指视为无效的工作程序指标条目的数量。 指标级别：汇总 单位：计数  | 
|  NumWorkersWithFailingWorkerMetric  |  指工作程序指标条目数量，其中一个工作程序指标值为 -1（表示工作程序指标值不可用）。 指标级别：汇总 单位：计数  | 
|  LeaseDeserializationFailureCount  |  指租约表中未能反序列化的租约条目。 指标级别：汇总 单位：计数  | 

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

`InitializeTask` 操作负责初始化 KCL 应用程序的记录处理器。此操作的逻辑包括从 Kinesis Data Streams 中获取分片迭代器并初始化记录处理程序。


| 指标 | 说明 | 
| --- | --- | 
| KinesisDataFetcher.getiterator.Success |  每个 KCL 应用程序的成功 `GetShardIterator` 操作数。 指标级别：详细 单位：计数  | 
| KinesisDataFetcher.getiterator.time |  给定 KCL 应用程序的每个 `GetShardIterator` 操作所花费的时间。 指标级别：详细 单位：毫秒  | 
| RecordProcessor.initialize.tim |  记录处理器的初始化方法所花费的时间。 指标级别：汇总 单位：毫秒  | 
| 成功 |  成功的记录处理程序初始化的数目。 指标级别：汇总 单位：计数  | 
| 时间 |  KCL 工作程序初始化记录处理器所花费的时间。 指标级别：汇总 单位：毫秒  | 

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

`ShutdownTask` 操作初始化分片处理的关闭顺序。这可能是因为分片被拆分或合并，或者当分片租赁从工作程序中丢失时。在这两种情况下，将调用记录处理程序 `shutdown()` 函数。在分片被拆分或合并的情况下也会发现新的分片，这将创建一个或两个新的分片。


| 指标 | 说明 | 
| --- | --- | 
| CreateLease. 成功 |  新的子分片在父分片关闭后成功添加到 KCL 应用程序 DynamoDB 表的次数。 指标级别：详细 单位：计数  | 
| CreateLease.Time |  在 KCL 应用程序 DynamoDB 表中添加新的子分片信息所花费的时间。 指标级别：详细 单位：毫秒  | 
| UpdateLease. 成功 |  记录处理程序关闭期间成功的最终检查点的数目。 指标级别：详细 单位：计数  | 
| UpdateLease.Time |  记录处理程序关闭期间检查点操作所花费的时间。 指标级别：详细 单位：毫秒  | 
| RecordProcessor.shutdown.time |  记录处理器的关闭方法所花费的时间。 指标级别：汇总 单位：毫秒  | 
| 成功 |  成功的关闭任务的数目。 指标级别：汇总 单位：计数  | 
| 时间 |  KCL 工作程序关闭任务所花费的时间。 指标级别：汇总 单位：毫秒  | 

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

`ShardSyncTask` 操作会发现对 Kinesis 数据流的分片信息所做的更改，因此 KCL 应用程序可处理新的分片。


| 指标 | 说明 | 
| --- | --- | 
| CreateLease. 成功 |  将新的分片信息添加到 KCL 应用程序 DynamoDB 表的成功尝试次数。 指标级别：详细 单位：计数  | 
| CreateLease.Time |  在 KCL 应用程序 DynamoDB 表中添加新的分片信息所花费的时间。 指标级别：详细 单位：毫秒  | 
| 成功 |  成功的分片同步操作的数目。 指标级别：汇总 单位：计数  | 
| 时间 |  分片同步操作所花费的时间。 指标级别：汇总 单位：毫秒  | 

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

如果一个分片被拆分或与其他分片合并，则会创建新的子分片。`BlockOnParentTask` 操作确保新分片的记录处理在 KCL 完全处理父分片之前不会开始。


| 指标 | 说明 | 
| --- | --- | 
| 成功 |  父分片完成的成功检查的数目。 指标级别：汇总 单位：计数  | 
| 时间 |  父分片完成所花费的时间。 指标级别：汇总 单位：毫秒  | 

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

`PeriodicShardSyncManager` 负责检查 KCL 消费端应用程序正在处理的数据流、识别具有部分租约的数据流并转交出去进行同步。

将 KCL 配置为处理单个数据流（然后将和的值设置 NumStreamsWithPartialLeases 为 1） NumStreamsToSync 以及将 KCL 配置为处理多个数据流时，以下指标可用。


| 指标 | 说明 | 
| --- | --- | 
| NumStreamsToSync |  包含部分租约且必须移交以进行同步的使用者应用程序正在处理的数据流（每个 AWS 账户）的数量。 指标级别：汇总 单位：计数  | 
| NumStreamsWithPartialLeases |  使用者应用程序正在处理的包含部分租约的数据流（每个 AWS 账户）的数量。 指标级别：汇总 单位：计数  | 
| 成功 |  `PeriodicShardSyncManager` 能够成功识别消费端应用程序正在处理的数据流中部分租约的次数。 指标级别：汇总 单位：计数  | 
| 时间 |  `PeriodicShardSyncManager` 检查消费端应用程序正在处理的数据流以确定哪些数据流需要分片同步所花费的时间（以毫秒为单位）。 指标级别：汇总 单位：毫秒  | 

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

`MultistreamTracker` 接口能够让您构建可以同时处理多个数据流的 KCL 消费端应用程序。


| 指标 | 说明 | 
| --- | --- | 
| DeletedStreams.Count |  在指定时段内删除的数据流数量。 指标级别：汇总 单位：计数  | 
| ActiveStreams.Count |  正在处理的活动数据流的数量。 指标级别：汇总 单位：计数  | 
| StreamsPendingDeletion.Count |  依据 `FormerStreamsLeasesDeletionStrategy` 待删除的数据流的数量。 指标级别：汇总 单位：计数  | 

### Per-worker 指标
<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` 操作使用这些指标来执行租约分配。


| 指标 | 说明 | 
| --- | --- | 
|  InMemoryMetricStatsReporterFailure  |  指由于某些工作程序指标失效而无法捕获内存中工作程序指标值的次数。 指标级别：汇总 单位：计数  | 
|  WorkerMetricStatsReporter.Time  |  `WorkerMetricsStats` 操作花费的时间。 指标级别：汇总 单位：毫秒  | 
|  WorkerMetricStatsReporter. 成功  |  `WorkerMetricsStats` 操作已成功完成的次数。 指标级别：汇总 单位：计数  | 

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

`LeaseDiscovery` 操作负责确定由 `LeaseAssignmentManager` 操作分配给当前工作程序的新租约。此操作的逻辑包括通过读取租约表的全局二级索引来确定分配给当前工作程序的租约。


| 指标 | 说明 | 
| --- | --- | 
|  ListLeaseKeysForWorker.Time  |  指在租约表上调用全局二级索引并获取分配给当前工作程序的租约键的时间。 指标级别：详细 单位：毫秒  | 
|  FetchNewLeases.Time  |  指从租约表中获取所有新租约的时间。 指标级别：详细 单位：毫秒  | 
|  NewLeasesDiscovered  |  指分配给工作程序的新租约总数。 指标级别：详细 单位：计数  | 
|  时间  |  `LeaseDiscovery` 操作花费的时间。 指标级别：汇总 单位：毫秒  | 
|  成功  |  `LeaseDiscovery` 操作已成功完成的次数。 指标级别：汇总 单位：计数  | 
|  OwnerMismatch  |  指 GSI 响应和租约表的一致性读取中出现所有者不匹配的次数。 指标级别：详细 单位：计数  | 

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

`RenewAllLeases` 操作定期续订由特定工作程序实例拥有的分片租约。


| 指标 | 说明 | 
| --- | --- | 
| RenewLease. 成功 |  工作程序成功续订租约的数目。 指标级别：详细 单位：计数  | 
| RenewLease.Time |  租约续订操作所花费的时间。 指标级别：详细 单位：毫秒  | 
| CurrentLeases |  续订所有租约后由工作程序拥有的分片租约数。 指标级别：汇总 单位：计数  | 
| LostLeases |  在尝试续订由工作程序拥有的所有租约后丢失的分片租约数。 指标级别：汇总 单位：计数  | 
| 成功 |  工作程序的成功的租约续订操作次数。 指标级别：汇总 单位：计数  | 
| 时间 |  续订工作程序的所有租约所花费的时间。 指标级别：汇总 单位：毫秒  | 

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

`TakeLeases` 操作使所有 KCL 工作程序之间的记录处理达到平衡。如果当前 KCL 工作程序拥有的分片租约少于所需的分片租约，则将从已过载的另一个工作程序中提取分片租约。


| 指标 | 说明 | 
| --- | --- | 
| ListLeases. 成功 |  成功从 KCL 应用程序 DynamoDB 表中检索所有分片租约的次数。 指标级别：详细 单位：计数  | 
| ListLeases.Time |  从 KCL 应用程序 DynamoDB 表中检索所有分片租约所花费的时间。 指标级别：详细 单位：毫秒  | 
| TakeLease. 成功 |  工作程序成功从其他 KCL 工作程序中提取分片租约的次数。 指标级别：详细 单位：计数  | 
| TakeLease.Time |  利用该工作程序提取的租约更新租约表所花费的时间。 指标级别：详细 单位：毫秒  | 
| NumWorkers |  工作程序总数，由特定工作程序标识。 指标级别：汇总 单位：计数  | 
| NeededLeases |  当前工作程序为平衡分片处理负载所需的分片租约数。 指标级别：详细 单位：计数  | 
| LeasesToTake |  工作程序将尝试提取的租约的数目。 指标级别：详细 单位：计数  | 
| TakenLeases |  工作程序已成功提取的租约的数目。 指标级别：汇总 单位：计数   | 
| TotalLeases |  KCL 应用程序正在处理的分片的总数。 指标级别：详细 单位：计数  | 
| ExpiredLeases |  未由任何工作程序处理的分片的总数，由特定工作程序标识。 指标级别：汇总 单位：计数  | 
| 成功 |  `TakeLeases` 操作已成功完成的次数。 指标级别：汇总 单位：计数  | 
| 时间 |  工作程序的 `TakeLeases` 操作所花费的时间。 指标级别：汇总 单位：毫秒  | 

### Per-shard 指标
<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` 函数。


| 指标 | 说明 | 
| --- | --- | 
| KinesisDataFetcher.getRecords.Su |  每个 Kinesis 数据流分片的成功 `GetRecords` 操作数。 指标级别：详细 单位：计数  | 
| KinesisDataFetcher.getRecords.tim |  Kinesis 数据流分片的每个 `GetRecords` 操作所花费的时间。 指标级别：详细 单位：毫秒  | 
| UpdateLease. 成功 |  给定分片的记录处理程序完成的成功检查点的数目。 指标级别：详细 单位：计数  | 
| UpdateLease.Time |  给定分片的每个检查点操作所花费的时间。 指标级别：详细 单位：毫秒  | 
| DataBytesProcessed |  每个 `ProcessTask` 调用所处理的记录的总大小（以字节为单位）。 指标级别：汇总 单位：字节  | 
| RecordsProcessed |  每个 `ProcessTask` 调用所处理的记录的数量。 指标级别：汇总 单位：计数  | 
| ExpiredIterator |  呼叫时 ExpiredIteratorException 收到的数量`GetRecords`。 指标级别：汇总 单位：计数  | 
| MillisBehindLatest | 当前迭代器晚于分片中最新记录 (tip) 的时间。此值为小于或等于响应中最新一条记录的时间和当前时间之间的时差。与比较最新一条响应记录中的时间戳相比，此指标可以更精确地反映分片相对于末端的距离。此值适用于最近一批记录，而不是每条记录中所有时间戳的平均值。指标级别：汇总单位：毫秒 | 
| RecordProcessor.processRecords |  记录处理器的 `processRecords` 方法所花费的时间。 指标级别：汇总 单位：毫秒  | 
| 成功 |  成功处理任务操作的数目。 指标级别：汇总 单位：计数  | 
| 时间 |  处理任务操作所花费的时间。 指标级别：汇总 单位：毫秒  |