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

# KCL 組態
<a name="kcl-configuration"></a>

您可以設定組態屬性來自訂 Kinesis Client Library 的功能，以符合您的特定需求。下表說明組態屬性和類別。

**重要**  
在 KCL 3.x 中，負載平衡演算法旨在實現工作者之間的 CPU 使用率，而不是每個工作者的相同租用數量。設定`maxLeasesForWorker`太低，您可能會限制 KCL 有效平衡工作負載的能力。如果您使用 `maxLeasesForWorker`組態，請考慮增加其值，以允許獲得最佳的負載分佈。


**此資料表顯示 KCL 的組態屬性**  

| 組態屬性 | 組態類別 | Description | 預設值 | 
| --- | --- | --- | --- | 
| applicationName | ConfigsBuilder | 此 KCL 應用程式的名稱。用做為 tableName 和 consumerName 的預設值。 | 不適用 | 
| tableName | ConfigsBuilder | 允許覆寫用於 Amazon DynamoDB 租用資料表的資料表名稱。 | 不適用 | 
| streamName | ConfigsBuilder | 此應用程式從中處理其記錄的串流名稱。 | 不適用 | 
| workerIdentifier | ConfigsBuilder | 代表應用程式處理器本項實例的唯一識別符。其必須獨一無二。 | 不適用 | 
| failoverTimeMillis | LeaseManagementConfig | 將租用擁有者視為失敗前必須經過的毫秒數。對於具有大量碎片的應用程式，這可以設定為較高的數字，以減少追蹤租用所需的 DynamoDB IOPS 數量。 | 10，000 (10 秒） | 
| shardSyncIntervalMillis | LeaseManagementConfig | 碎片同步呼叫的時間。 | 60，000 (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 DynamoDB 讀取容量。如果您在組態中使用預設隨需容量模式，您可以忽略此billingMode組態。 | 10 | 
| initialLeaseTableWriteCapacity | LeaseManagementConfig | 當 Kinesis Client Library 需要建立新的 DynamoDB 租用資料表時所使用的 DynamoDB 讀取容量。如果您在組態中使用預設隨需容量模式，您可以忽略此billingMode組態。 | 10 | 
| initialPositionInStreamExtended | LeaseManagementConfig | 應用程式應該在串流中開始的初始位置。這僅在初次建立租用時使用。 | InitialPositionInStream.TRIM\_HORIZON | 
| 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 />注意：檢查點必須在 RecordProcessor 的 shutdownRequested() 方法中實作，才能受益於正常的租賃交接功能。<br />這是 KCL 3.x 中引入的新組態。 | TRUE | 
| gracefulLeaseHandoffTimeoutMillis | LeaseManagementConfig | 指定等待目前碎片 RecordProcessor 正常關閉的最短時間 （以毫秒為單位），然後再將租約強制轉移給下一個擁有者。<br />如果您的 processRecords 方法執行時間通常超過預設值，請考慮增加此設定。這可確保 RecordProcessor 在租用轉移發生之前有足夠的時間完成處理。<br />這是 KCL 3.x 中引入的新組態。 | 30，000 (30 秒） | 
| maxRecords | PollingConfig | 允許設定 Kinesis 傳回的記錄數上限。 | 10,000 | 
| retryGetRecordsInSeconds | PollingConfig | 為故障設定 GetRecords 嘗試間的延遲。 | 無 | 
| maxGetRecordsThreadPool | PollingConfig | 用於 GetRecords 的執行緒集區大小。 | 無 | 
| idleTimeBetweenReadsInMillis | PollingConfig | 決定 KCL 在 GetRecords 呼叫之間等待多久從資料串流輪詢資料。單位為毫秒。 | 1,500 | 
| callProcessRecordsEvenForEmptyRecordList | ProcessorConfig | 設定時，即使 Kinesis 無提供任何記錄也會呼叫記錄處理器。 | FALSE | 
| parentShardPollIntervalMillis | CoordinatorConfig | 記錄處理器應該輪詢以檢查父碎片是否已完成的頻率。單位為毫秒。 | 10，000 (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 之前緩衝指標的持續時間上限 （以毫秒為單位）。 | 10，000 (10 秒） | 
| metricsMaxQueueSize | MetricsConfig | 指定發佈至 CloudWatch 之前要緩衝的指標數目上限。 | 10,000 | 
| metricsLevel | MetricsConfig | 指定要啟用和發佈的 CloudWatch 指標精細程度。<br />可能的值：NONE、SUMMARY、DETAILED。 | MetricsLevel.DETAILED | 
| metricsEnabledDimensions | MetricsConfig | 控制 CloudWatch 指標的允許維度。 | 所有維度 | 

**KCL 3.x 中已停止的組態**

下列組態屬性會在 KCL 3.x 中停止：


**資料表顯示 KCL 3.x 的已停止組態屬性**  

| 組態屬性 | 組態類別 | Description | 
| --- | --- | --- | 
| 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 相容模式時，需要這些已停止的組態。