翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# 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 を減らすために、この値をより大きく設定する場合があります。 | 10,000 (10 秒) | 
| shardSyncIntervalMillis | LeaseManagementConfig | シャード同期コールの間隔。 | 60,000 (60 秒) | 
| cleanupLeasesUponShardCompletion | LeaseManagementConfig | 設定すると、子リースの処理が開始されると即時にリースが削除されます。 | TRUE | 
| ignoreUnexpectedChildShards | LeaseManagementConfig | 設定すると、開いているシャードがある子シャードは無視されます。これは、主に DynamoDB Streams 用です。 | FALSE | 
| maxLeasesForWorker | LeaseManagementConfig | 1 つのワーカーが受け持つことができるリースの最大数です。この値を低く設定しすぎると、ワーカーがすべてのシャードを処理できず、データ損失を招く可能性があります。また、ワーカー間のリース割り当てが最適にならない原因にもなります。設定する際は、シャード合計数、ワーカー数、ワーカーの処理能力を考慮してください。 | 無制限 | 
| maxLeaseRenewalThreads | LeaseManagementConfig | リース更新スレッドプールのサイズを制御します。アプリケーションが処理するリースの数が多いほど、このプールも大きくする必要があります。 | 20 | 
| billingMode | LeaseManagementConfig | DynamoDB に作成されるリーステーブルのキャパシティモードを決定します。選択肢はオンデマンドモード (PAY\_PER\_REQUEST) とプロビジョンドモードの 2 種類です。容量計画を行う必要がなく、ワークロードに応じて自動的にスケールするため、デフォルト設定であるオンデマンドモードの使用をお勧めします。 | 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\_HORIZON | 
| reBalanceThresholdPercentage | LeaseManagementConfig | 負荷分散アルゴリズムがワーカー間でシャードの再割り当てを検討するタイミングを決定する、パーセンテージ値です。<br />これは、KCL 3.x で導入された新しい設定です。 | 10 | 
| dampeningPercentage | LeaseManagementConfig | 1 回のリバランス処理で、過負荷状態のワーカーから移動させる負荷量を抑制するために使用されるパーセンテージ値です。<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 の廃止された設定プロパティを示しています。**  

| 設定プロパティ | 設定クラス | 説明 | 
| --- | --- | --- | 
| 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 互換モードで動作している間は、これらの廃止された設定が必要になります。