再試行戦略戦略を指定する戦略をカスタマイズする RetryPolicy から RetryStrategy への移行

再試行

への呼び出し AWS のサービスは、予期しない理由で失敗することがあります。スロットリング (レート超過) や一時的なエラーなどの特定のエラーは、呼び出しを再試行すると成功する可能性があります。 AWS SDK for Java 2.x には、このようなエラーを検出し、すべてのクライアントでデフォルトで有効になっている呼び出しを自動的に再試行するメカニズムが組み込まれています。

このページでは、この仕組み、個別のモードの設定方法、再試行動作の調整方法について説明します。

再試行戦略

再試行戦略は、再試行を実装SDKするためにで使用されるメカニズムです。各SDKクライアントには、クライアントの構築後に変更できない、ビルド時に作成された再試行戦略があります。

再試行戦略には以下の責任があります。

例外を再試行可能または不可として分類します。
提案された遅延を計算して、次の試行まで待ちます。
リクエストの大部分が失敗し、再試行が失敗したときに再試行を停止するメカニズムを提供するトークンバケットを維持します。

注記

バージョン 2.26.0 で再試行戦略をリリースする前にSDK、再試行ポリシーはで再試行メカニズムを提供しましたSDK。再試行ポリシーAPIはsoftware.amazon.awssdk.core.retryパッケージ内のコアRetryPolicyクラスで構成されますが、software.amazon.awssdk.retriesパッケージには再試行戦略API要素が含まれています。

再試行戦略APIは、のコアコンポーネントのインターフェイスと動作を統一するための AWS全体の取り組みの一環として導入されましたSDKs。

SDK for Java 2.x には、標準、レガシー、アダプティブの 3 つの再試行戦略が組み込まれています。3 つの再試行戦略はすべて、一連の再試行可能な例外で再試行するように事前設定されています。再試行可能なエラーの例としては、ソケットタイムアウト、サービス側のスロットリング、同時実行または楽観的なロック障害、一時的なサービスエラーなどがあります。

標準再試行戦略

標準の再試行戦略は、通常のユースケースで推奨されるRetryStrategy実装です。とは異なりAdaptiveRetryStrategy、標準戦略は、すべての再試行ユースケースで一般的に役立ちます。

デフォルトでは、標準再試行戦略は以下を実行します。

ビルド時に設定された条件を再試行します。これはで調整できますStandardRetryStrategy.Builder#retryOnException。
再試行回数は 2 回で、合計 3 回です。これはで調整できますStandardRetryStrategy.Builder#maxAttempts(int)。
スロットリング以外の例外の場合、BackoffStrategy#exponentialDelayバックオフ戦略を使用します。基本遅延は 100 ミリ秒、最大遅延は 20 秒です。これはで調整できますStandardRetryStrategy.Builder#backoffStrategy。
スロットリング例外の場合、BackoffStrategy#exponentialDelayバックオフ戦略を使用します。基本遅延は 1 秒、最大遅延は 20 秒です。これはで調整できますStandardRetryStrategy.Builder#throttlingBackoffStrategy。
ダウンストリームの障害が高い場合に回路切断 (再試行の無効化) を実行します。最初の試行は常に実行され、再試行のみが無効になります。で調整しますStandardRetryStrategy.Builder#circuitBreakerEnabled。

レガシー再試行戦略

レガシー再試行戦略は、通常のユースケースRetryStrategyではですが、のために廃止されますStandardRetryStrategy。これは、別の戦略を指定しない場合にクライアントが使用するデフォルトの再試行戦略です。

これは、スロットリング例外と非スロットリング例外を異なる方法で処理することを特徴とし、スロットリング例外の場合、バックオフのベース遅延は、スロットリング以外の例外のベース遅延 (100 ミリ秒) よりも大きく (500 ミリ秒）、スロットリング例外はトークンバケットの状態に影響を与えません。

内部でこの戦略を大規模に使用した経験 AWS から、は標準の再試行戦略よりも特に優れていないことがわかりました。さらに、ダウンストリームサービスを再試行の嵐から保護できず、クライアント側のリソース不足につながる可能性があります。

デフォルトでは、レガシー再試行戦略は以下を実行します。

ビルド時に設定された条件を再試行します。これはで調整できますLegacyRetryStrategy.Builder#retryOnException。
再試行回数は 3 回で、合計 4 回です。これはで調整できますLegacyRetryStrategy.Builder#maxAttempts(int)。
スロットリング以外の例外の場合、BackoffStrategy#exponentialDelayバックオフ戦略を使用します。基本遅延は 100 ミリ秒、最大遅延は 20 秒です。これは、で調整できます。 LegacyRetryStrategy.Builder#backoffStrategy.
スロットリング例外の場合、BackoffStrategy#exponentialDelayバックオフ戦略を使用します。基本遅延は 500 ミリ秒、最大遅延は 20 秒です。これはで調整できますLegacyRetryStrategy.Builder#throttlingBackoffStrategy。
ダウンストリームの障害が高い場合に回路切断 (再試行の無効化) を実行します。サーキットブレークは、最初の試行の成功を妨げることはありません。この動作はで調整できますLegacyRetryStrategy.Builder#circuitBreakerEnabled。
サーキットブレーカーの状態は、スロットリング例外の影響を受けません。

アダプティブ再試行戦略

アダプティブ再試行戦略は、リソースの制約が高いユースケースRetryStrategy向けのです。

アダプティブ再試行戦略には、標準戦略のすべての機能が含まれており、スロットリングされていないリクエストと比較したスロットリングされたリクエストのレートを測定するクライアント側のレートリミッターが追加されています。この戦略では、この測定を使用して、安全な帯域幅内に留まるためにリクエストを遅くし、スロットリングエラーをゼロにするのが理想的です。

デフォルトでは、アダプティブ再試行戦略は以下を実行します。

ビルド時に設定された条件を再試行します。これはで調整できますAdaptiveRetryStrategy.Builder#retryOnException。
再試行回数は 2 回で、合計 3 回です。これはで調整できますAdaptiveRetryStrategy.Builder#maxAttempts(int)。
ダウンストリームリソースに対する現在の負荷に基づく動的バックオフ遅延を使用します。
ダウンストリーム障害の数が多い場合に、回路切断 (再試行の無効化) を実行します。回路が切断されると、ダウンストリームサービスを保護するために停止シナリオで 2 回目の試行が妨げられる可能性があります。

警告

アダプティブ再試行戦略は、クライアントが単一のリソース (1 つの DynamoDB テーブルまたは 1 つの Amazon S3 バケットなど) に対して動作することを前提としています。

1 つのクライアントを複数のリソースに使用すると、1 つのリソースに関連付けられたスロットリングまたは停止により、クライアントが他のすべてのリソースにアクセスするときにレイテンシーが増加し、障害が発生します。アダプティブ再試行戦略を使用する場合は、リソースごとに 1 つのクライアントを使用することをお勧めします。

また、すべてのクライアントがリソースに対してアダプティブ再試行戦略を使用する状況では、この戦略を使用することをお勧めします。

重要

Java の 2.26.0 を使用した再試行戦略のリリースには、新しいRetryMode.ADAPTIVE_V2列挙値SDKが含まれています。このADAPTIVE_V2モードでは、スロットリングエラーが以前に検出されたときに最初の試行を遅延できなかったエラーを修正します。

2.26.0 リリースでは、ユーザーは環境変数、システムプロパティ、またはプロファイル設定adaptiveと同様にモードを設定することで、ADAPTIVE_V2モードの動作を自動的に取得します。これらの設定にはadaptive_v2値がありません。モードの設定方法については、以下の戦略を指定するセクションを参照してください。

ユーザーは、を使用してコードでモードを設定することで、以前の動作を取得できますRetryMode.ADAPTIVE。

概要: 再試行戦略のデフォルト値の比較

次の表は、各再試行戦略のプロパティのデフォルト値を示しています。

方針	最大試行回数	スロットリング以外のエラーのベース遅延	スロットリングエラーのベース遅延	トークンバケットサイズ	スロットリング以外の再試行あたりのトークンコスト	スロットリング再試行あたりのトークンコスト
標準	3	100	100	500	5	5
レガシー	4	100	500	500	5	0
アダプティブ	3	100	100	500	5	5

戦略を指定する

サービスクライアントの戦略を指定する方法は 4 つあります。

コード内

クライアントを構築するときは、再試行戦略を使用して lambda 式を設定できます。次のスニペットは、DynamoDB サービスクライアントのデフォルト値を使用する標準再試行戦略を設定します。


DynamoDbClient client = DynamoDbClient.builder()
        .overrideConfiguration(o -> o.retryStrategy(RetryMode.STANDARD))
        .build();

RetryMode.ADAPTIVE の代わりに RetryMode.LEGACYまたはを指定できますRetryMode.STANDARD。

プロファイル設定として

共有 AWS 設定ファイルにプロファイル設定retry_modeとしてを含めます。standard、legacy、またはを値adaptiveとして指定します。プロファイル設定として設定すると、プロファイルがアクティブな間に作成されるすべてのサービスクライアントは、指定された再試行戦略をデフォルト値で使用します。この設定は、前述のように再試行戦略をコードで設定することで上書きできます。

次のプロファイルでは、すべてのサービスクライアントが標準の再試行戦略を使用します。


[profile dev]
region = us-east-2
retry_mode = standard

JVM システムプロパティとして

システムプロパティを使用して、コードで上書きされない限り、すべてのサービスクライアントに再試行ステートジーを設定できますaws.retryMode。standard、legacy、またはを値adaptiveとして指定します。

次のコマンドに示すように Java を呼び出すときは、 -Dスイッチを使用します。


java -Daws.retryMode=standard ...

または、次のスニペットに示すように、クライアントを作成する前にコードにシステムプロパティを設定します。


public void main(String[] args) {
    // Set the property BEFORE any AWS service clients are created.
    System.setProperty("aws.retryMode", "standard");
    ...
}

環境変数を使用する

AWS_RETRY_MODE 環境変数は、、standard、legacyまたはの値でも使用できますadaptive。プロファイル設定またはJVMシステムプロパティと同様に、環境変数は、コードでクライアントを設定しない限り、すべてのサービスクライアントを指定された再試行モードで設定します。

次のコマンドは、現在のシェルセッションstandardの再試行モードをに設定します。


export AWS_RETRY_MODE=standard

戦略をカスタマイズする

再試行可能な最大試行数、バックオフ戦略、例外を設定することで、任意の再試行戦略をカスタマイズできます。再試行戦略を構築する場合やクライアントを構築する場合は、設定された戦略をさらに改良できるオーバーライドビルダーを使用してカスタマイズできます。

最大試行回数をカスタマイズする

次のステートメントに示すように、クライアント構築中の最大試行回数を設定できます。次のステートメントでは、クライアントのデフォルトの再試行戦略を、最初の試行と 4 回の再試行の最大 5 回にカスタマイズします。


DynamoDbClient client = DynamoDbClient.builder()
        .overrideConfiguration(o -> o.retryStrategy(b -> b.maxAttempts(5)))
        .build();

または、次のコード例のように、戦略を構築し、クライアントに提供することもできます。次のコードは、標準の 3 回の最大試行回数を 10 回に置き換え、カスタマイズされた戦略で DynamoDB クライアントを設定します。


StandardRetryStrategy strategy = AwsRetryStrategy.standardRetryStrategy()
         .toBuilder()
         .maxAttempts(10)
         .build();
DynamoDbClient client = DynamoDbClient.builder()
        .overrideConfiguration(o -> o.retryStrategy(strategy))
        .build();

警告

各クライアントを一意のRetryStrategyインスタンスで設定することをお勧めします。RetryStrategy インスタンスが共有されている場合、一方のクライアントで障害が発生すると、もう一方のクライアントの再試行動作に影響する可能性があります。

また、コードの代わりに外部設定を使用して、すべてのクライアントの最大試行回数を設定することもできます。この設定は、戦略を指定するセクションの説明に従って設定します。

再試行可能な例外をカスタマイズする

クライアント構築中に廃止をトリガーする追加の例外を設定できます。このカスタマイズは、再試行可能な例外のデフォルトセットに含まれていない例外がスローされるエッジケースに対して提供されます。

次のコードスニペットは、再試行例外retryOnExceptionをカスタマイズするために使用する方法を示していますretryOnExceptionOrCause。が直接例外をSDKスローする場合、または例外がラップされている場合、retryOnExceptionOrCauseメソッドは再試行可能な例外を追加します。


DynamoDbClient client = DynamoDbClient.builder()
        .overrideConfiguration(o -> o.retryStrategy(
                 b -> b.retryOnException(EdgeCaseException.class)
                       .retryOnExceptionOrCause(WrappedEdgeCaseException.class)))
        .build();

バックオフ戦略をカスタマイズする

バックオフ戦略を構築し、クライアントに提供できます。

次のコードは、デフォルトの標準戦略の指数遅延バックオフ戦略を置き換えBackoffStrategyるを構築します。


BackoffStrategy backoffStrategy = 
        BackoffStrategy.exponentialDelay(Duration.ofMillis(150),  // The base delay.
                                         Duration.ofSeconds(15)); // The maximum delay.
DynamoDbClient client = DynamoDbClient.builder()
        .overrideConfiguration(o -> o.retryStrategy(
                b -> b.backoffStrategy(backoffStrategy)))
        .build();

`RetryPolicy` から `RetryStrategy` への移行

RetryPolicy (再試行ポリシー API) は、近い将来にサポートされます。現在、のインスタンスを使用してクライアントRetryPolicyを設定すると、すべてが以前と同じように機能します。シーンの背後では、Java はそれをにSDK適応させますRetryStrategy。新しい再試行戦略インターフェイスは、と同じ機能を提供しますRetryPolicyが、作成および設定は異なります。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

例外処理

ログ記録