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

# KCL 配置
<a name="kcl-configuration"></a>

您可以设置配置属性来自定义 Kinesis Client Library 的功能，以满足具体要求。下表列明了配置属性和类。

**重要**  
在 KCL 3.x 中，负载均衡算法的目标是在各工作程序之间实现均匀的 CPU 使用率，而不是使各个工作程序的租约数量相等。如果 `maxLeasesForWorker` 设置得太低，可能会限制 KCL 有效平衡工作负载的能力。如果使用 `maxLeasesForWorker` 配置，可考虑增加其值以实现最佳的负载分布。


**本表显示了 KCL 的配置属性**  

| 配置属性 | 配置类 | 说明 | 默认 值 | 
| --- | --- | --- | --- | 
| applicationName | ConfigsBuilder | 此 KCL 应用程序的名称。用作 tableName 和 consumerName 的默认名称。 | 不适用 | 
| tableName | ConfigsBuilder | 允许覆盖用于 Amazon DynamoDB 租赁表的表名称。 | 不适用 | 
| streamName | ConfigsBuilder | 此应用程序从其中处理记录的流的名称。 | 不适用 | 
| workerIdentifier | ConfigsBuilder | 表示应用程序处理器的这种实例化的唯一标识符。此值必须唯一。 | 不适用 | 
| failoverTimeMillis | LeaseManagementConfig | 在您可以将租赁所有者视为已失败之前必须经过的毫秒数。对于拥有大量分片的应用程序，可以将分片数设置为更高的数字，以减少跟踪租约所需的 DynamoDB IOPS 数。 | 10000（10 秒） | 
| shardSyncIntervalMillis | LeaseManagementConfig | 分片同步调用之间的时间。 | 60000（60 秒） | 
| cleanupLeasesUponShardCompletion | LeaseManagementConfig | 如果设置，只要子租赁已开始处理，即可删除租赁。 | TRUE | 
| ignoreUnexpectedChildShards | LeaseManagementConfig | 如果设置，将忽略具有打开的分片的子分片。这主要适用于 DynamoDB Streams。 | FALSE | 
| maxLeasesForWorker | LeaseManagementConfig | 单个工作程序应接受的最大租约数。如果设置太低，则在工作程序无法处理所有分片时可能会导致数据丢失，并造成工作程序之间的租约分配不够理想。在进行配置时，应考虑总分片数、工作程序数和工作程序的处理能力。 | 无限制 | 
| maxLeaseRenewalThreads | LeaseManagementConfig | 控制租赁续订线程池的大小。您的应用程序可以容纳的租赁越多，此池应该就越大。 | 20 | 
| billingMode | LeaseManagementConfig | 确定 DynamoDB 中创建的租约表的容量模式。容量模式有两个选项：按需模式 (PAY\_PER\_REQUEST) 和预置模式。我们建议使用默认的按需模式设置，因为这种模式可以自动扩缩以适应工作负载，而无需进行容量规划。 | PAY\_PER\_REQUEST（按需模式） | 
| initialLeaseTableReadCapacity | LeaseManagementConfig | 如果 Kinesis Client Library 需要使用预置的容量模式创建新的 DynamoDB 租约表，DynamoDB 将读取使用的容量。如果在 billingMode 配置中使用默认的按需容量模式，可以忽略上述配置。 | 10 | 
| initialLeaseTableWriteCapacity | LeaseManagementConfig | 如果 Kinesis Client Library 需要创建新的 DynamoDB 租约表，DynamoDB 将读取使用的容量。如果在 billingMode 配置中使用默认的按需容量模式，可以忽略上述配置。 | 10 | 
| initialPositionInStreamExtended | LeaseManagementConfig | 应用程序应在流中开始的初始位置。此值仅在创建初始租赁时使用。 | InitialPositionInStream.TRIM\_地平线 | 
| reBalanceThresholdPercentage | LeaseManagementConfig | 用于确定负载均衡算法何时应考虑在工作程序之间重新分配分片的一个百分比值。<br />这是 KCL 3.x 中引入的新配置。 | 10 | 
| dampeningPercentage | LeaseManagementConfig | 用于抑制单次再平衡操作中将从超载工作程序转移的负载量的一个百分比值。<br />这是 KCL 3.x 中引入的新配置。 | 60 | 
| allowThroughputOvershoot | LeaseManagementConfig | 确定是否仍需要从超载工作程序获得额外的租约，即使这会导致占用的总租约吞吐量超过所需的吞吐量。<br />这是 KCL 3.x 中引入的新配置。 | TRUE | 
| disableWorkerMetrics | LeaseManagementConfig | 确定在重新分配租约和负载均衡时，KCL 是否应忽略工作程序的资源指标（例如 CPU 利用率）。如果要阻止 KCL 根据 CPU 利用率进行负载均衡，则将其设置为 TRUE。<br />这是 KCL 3.x 中引入的新配置。 | FALSE | 
| maxThroughputPerHostKBps | LeaseManagementConfig | 在租约分配期间分配给工作程序的最大吞吐量。<br />这是 KCL 3.x 中引入的新配置。 | 无限制 | 
| isGracefulLeaseHandoffEnabled | LeaseManagementConfig | 控制工作程序之间的租约移交行为。设置为 true 时，KCL 将尝试通过在将租约移交给其他工作人员之前让分片 RecordProcessor 有足够的时间完成处理来优雅地转移租约。这有助于确保数据完整性和平稳过渡，但可能会增加移交时间。<br />如果设置为 false，则租约将立即移交，无需等待优雅 RecordProcessor 地关闭。这可以加快移交速度，但可能存在处理不完全的风险。<br />注意：检查点必须在的 shutdownRequested () 方法中实现， RecordProcessor 才能从优雅的租赁移交功能中受益。<br />这是 KCL 3.x 中引入的新配置。 | TRUE | 
| gracefulLeaseHandoffTimeoutMillis | LeaseManagementConfig | 指定在强制将租约转让给下一个所有者之前，等待当前分片正常关闭的最短时间（ RecordProcessor 以毫秒为单位）。<br />如果 processRecords 方法的典型运行时间比默认值长，可考虑增加此设置。这样可以确保在租赁转让发生之前 RecordProcessor 有足够的时间完成其处理。<br />这是 KCL 3.x 中引入的新配置。 | 30000（30 秒） | 
| maxRecords | PollingConfig | 允许设置 Kinesis 返回的最大记录数。 | 10000 | 
| retryGetRecordsInSeconds | PollingConfig | 配置 GetRecords 尝试失败之间的延迟。 | 无 | 
| maxGetRecordsThreadPool | PollingConfig | 使用的线程池大小 GetRecords。 | 无 | 
| idleTimeBetweenReadsInMillis | PollingConfig | 确定 KCL 在两次 GetRecords 调用轮询数据流数据之间等待多长时间。单位为毫秒。 | 1500 | 
| callProcessRecordsEvenForEmptyRecordList | ProcessorConfig | 如果设置，即使 Kinesis 中未提供任何记录，也会调用记录处理器。 | FALSE | 
| parentShardPollIntervalMillis | CoordinatorConfig | 记录处理器应轮询多少时间才能查看是否已完成父分片。单位为毫秒。 | 10000（10 秒） | 
| skipShardSyncAtWorkerInitializationIfLeaseExist | CoordinatorConfig | 如果租赁表包含现有租赁，请禁用同步的分片数据。 | FALSE | 
| shardPrioritization | CoordinatorConfig | 要使用的分片优先级。 | NoOpShardPrioritization | 
| ClientVersionConfig | CoordinatorConfig | 确定应用程序将运行在哪个 KCL 版本兼容模式下。此配置仅适用于从之前的 KCL 版本进行迁移的情况。迁移至 3.x 时，需要将该配置设置为 `CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X`。完成迁移后，即可删除此配置。 | CLIENT\_VERSION\_CONFIG\_3X | 
| taskBackoffTimeMillis | LifecycleConfig | 等待重试 KCL 失败任务的时间。单位为毫秒。 | 500（0.5 秒） | 
| logWarningForTaskAfterMillis | LifecycleConfig | 任务尚未完成的情况下在记录警告之前要等待的时长。 | 无 | 
| listShardsBackoffTimeInMillis | RetrievalConfig | 发生故障时在调用 ListShards 之间要等待的时间（以毫秒为单位）。单位为毫秒。 | 1,500（1.5 秒） | 
| maxListShardsRetryAttempts | RetrievalConfig | ListShards 在放弃之前重试的最长时间。 | 50 | 
| metricsBufferTimeMillis | MetricsConfig | 指定在发布指标之前缓冲指标的最大持续时间（以毫秒为单位）。 CloudWatch | 10000（10 秒） | 
| metricsMaxQueueSize | MetricsConfig | 指定发布到之前要缓冲的最大指标数 CloudWatch。 | 10000 | 
| metricsLevel | MetricsConfig | 指定要启用和发布的 CloudWatch 指标的粒度级别。<br />可能的值：NONE、SUMMARY、DETAILED。 | MetricsLevel.DETAILED | 
| metricsEnabledDimensions | MetricsConfig | 控制 CloudWatch 指标允许的维度。 | 所有维度 | 

**KCL 3.x 中停用的配置**

以下配置属性在 KCL 3.x 中已停用：


**下表显示了 KCL 3.x 已停用的配置属性**  

| 配置属性 | 配置类 | 说明 | 
| --- | --- | --- | 
| maxLeasesToStealAtOneTime | LeaseManagementConfig | 应用程序一次应尝试窃取的最大租赁数量。KCL 3.x 会忽略此配置，并根据工作程序的资源利用率重新分配租约。 | 
| enablePriorityLeaseAssignment | LeaseManagementConfig | 控制工作程序是否应优先考虑已过期的租约（租约未续订的时间达故障转移时间的 3 倍）和新的分片租约，而不管目标租约数如何，但仍需遵守最大租约限制。KCL 3.x 会忽略此配置，并始终将过期租约分布到各个工作程序中。 | 

**重要**  
在从之前的 KCL 版本迁移至 KCL 3.x 时，仍必须拥有停用的配置属性。在迁移过程中，KCL 工作程序首先从 KCL 2.x 兼容模式启动，然后在检测到应用程序的所有 KCL 工作程序做好运行 KCL 3.x 的准备时切换到 KCL 3.x 功能模式。当 KCL 工作程序运行 KCL 2.x 兼容模式时，需要这些停用的配置。