Wiederholungen im AWS SDK für Kotlin

Aufrufe geben AWS-Services gelegentlich unerwartete Ausnahmen zurück. Bestimmte Arten von Fehlern, wie Drosselungen oder vorübergehende Fehler, können erfolgreich sein, wenn der Aufruf erneut versucht wird.

Auf dieser Seite wird beschrieben, wie Wiederholungsversuche automatisch AWS SDK für Kotlin verarbeitet werden und wie Sie das Wiederholungsverhalten für Ihre Anwendungen anpassen können.

Grundlegendes zum Verhalten bei Wiederholungen

In den folgenden Abschnitten wird erklärt, wie das SDK festlegt, wann Anfragen wiederholt werden müssen und welche Ausnahmen als Wiederholungsversuche gelten.

Standardkonfiguration für Wiederholungsversuche

Standardmäßig wird jeder Service-Client automatisch mit einer standardmäßigen Wiederholungsstrategie konfiguriert. In der Standardkonfiguration wird ein Anruf versucht, der bis zu dreimal fehlschlägt (der erste Versuch plus zwei Wiederholungsversuche). Die dazwischenliegende Verzögerung zwischen den einzelnen Aufrufen ist mit exponentiellem Backoff und zufälligem Jitter konfiguriert, um Wiederholungsversuche zu vermeiden. Diese Konfiguration funktioniert für die meisten Anwendungsfälle, kann jedoch unter bestimmten Umständen ungeeignet sein, z. B. bei Systemen mit hohem Durchsatz.

Das SDK versucht es nur bei Fehlern, die wiederholt werden können. Beispiele für Fehler, die wiederholt werden können, sind Socket-Timeouts, dienstseitige Drosselung, parallele oder optimistische Sperren sowie vorübergehende Dienstfehler. Fehlende oder ungültige Parameter, authentication/security Fehler und Ausnahmen bei Fehlkonfigurationen gelten nicht als wiederholbar.

Sie können die standardmäßige Wiederholungsstrategie anpassen, indem Sie die maximale Anzahl an Versuchen, Verzögerungen und Backoffs sowie die Token-Bucket-Konfiguration festlegen.

Welche Ausnahmen können wiederholt werden?

Der AWS SDK für Kotlin verwendet eine vorkonfigurierte Wiederholungsrichtlinie, die festlegt, welche Ausnahmen wiederholt werden können. Die Service-Client-Konfiguration verfügt über eine retryPolicy Eigenschaft, die angibt, welche Richtlinie auf Wiederholungsversuche angewendet wird. Wenn kein benutzerdefinierter Wert angegeben ist, ist AwsRetryPolicyder Standardwert.

Die folgenden Ausnahmen werden als wiederholbar eingestuft durch: AwsRetryPolicy

Wiederholbar anhand des Fehlercodes

Alle ServiceException mit einem sdkErrorMetadata.errorCode von:

• BandwidthLimitExceeded

• EC2ThrottledException

• IDPCommunicationError

• LimitExceededException

• PriorRequestNotComplete

• ProvisionedThroughputExceededException

• RequestLimitExceeded

• RequestThrottled

• RequestThrottledException

• RequestTimeout

• RequestTimeoutException

• SlowDown

• ThrottledException

• Throttling

• ThrottlingException

• TooManyRequestsException

• TransactionInProgressException

Kann mit dem HTTP-Statuscode erneut versucht werden

Alle ServiceException mit einem sdkErrorMetadata.statusCode von:

• 500 (Interner Servicefehler)

• 502 (Schlechtes Gateway)

• 503 (Dienst nicht verfügbar)

• 504 (Gateway-Timeout)

Je nach Fehlertyp erneut versuchbar

Alle ServiceException mit einem sdkErrorMetadata.errorType von:

• ErrorType.Server(z. B. interne Servicefehler)

• ErrorType.Client(z. B. eine ungültige Anfrage, eine Ressource nicht gefunden, Zugriff verweigert usw.)

Mit SDK-Metadaten erneut versuchbar

IrgendwoSdkBaseException:

• sdkErrorMetadata.isRetryableist true (z. B. ein clientseitiges Timeout, ein networking/socket Fehler usw.)

• sdkErrorMetadata.isThrottlingist true (z. B. zu viele Anfragen in kurzer Zeit stellen)

Eine vollständige Liste der Ausnahmen, die von jedem Service-Client ausgelöst werden können, finden Sie in der dienstspezifischen API-Referenzdokumentation.

Prüfen Sie, ob eine Ausnahme erneut versucht werden kann

Um festzustellen, ob das SDK eine Ausnahme als wiederholbar erachtet, überprüfen Sie die Eigenschaft für abgefangene Ausnahmen: isRetryable

try {
    dynamoDbClient.putItem {
        tableName = "MyTable"
        item = mapOf("id" to AttributeValue.S("123"))
    }
} catch (e: SdkBaseException) {
    println("Exception occurred: ${e.message}")
    
    if (e.sdkErrorMetadata.isRetryable) {
        println("This exception is retryable - SDK will automatically retry")
        println("If you're seeing this, retries may have been exhausted")
    } else {
        println("This exception is not retryable - fix the underlying issue")
        
        // Common non-retryable scenarios.
        when {
            e.message?.contains("ValidationException") == true -> 
                println("Check your request parameters")
            e.message?.contains("AccessDenied") == true -> 
                println("Check your IAM permissions")
            e.message?.contains("ResourceNotFound") == true -> 
                println("Verify the resource exists")
        }
    }
}

Welche Ausnahmen erreichen Ihren Code, wenn Wiederholungsversuche fehlschlagen

Wenn der Wiederholungsmechanismus des SDK ein Problem nicht lösen kann, werden Ausnahmen in Ihrem Anwendungscode ausgelöst. Wenn Sie diese Ausnahmetypen verstehen, können Sie eine angemessene Fehlerbehandlung implementieren. Dies sind nicht die Ausnahmen, die Wiederholungen auslösen — diese werden intern vom SDK behandelt.

Ihr Code erfasst die catch Arten von Ausnahmen, wenn die Wiederholungsversuche erschöpft oder deaktiviert sind:

Serviceausnahmen nach Erschöpfung der Wiederholungsversuche

Wenn alle Wiederholungsversuche fehlschlagen, fängt Ihr Code die letzte Serviceausnahme (Unterklasse vonAwsServiceException) ab, die zum Fehlschlagen des letzten Wiederholungsversuchs geführt hat. Dies kann ein Drosselungsfehler, ein Serverfehler oder eine andere dienstspezifische Ausnahme sein, die das SDK nicht durch Wiederholungen lösen konnte.

Netzwerkausnahmen nach Erschöpfung des Wiederholungsversuchs

Wenn Netzwerkprobleme bei allen Wiederholungsversuchen bestehen, erkennt Ihr Code ClientException Instanzen für Probleme wie Verbindungstimeouts, DNS-Auflösungsfehler und andere Verbindungsprobleme, die das SDK nicht lösen konnte.

Verwenden Sie das folgende Muster, um diese Ausnahmen in Ihrer Anwendung zu behandeln:

try {
    s3Client.getObject { 
        bucket = "amzn-s3-demo-bucket"
        key = "my-key" 
    }
} catch (e: AwsServiceException) {
    // Service-side errors that persisted through all retries.
    println("Service error after retries: ${e.errorDetails?.errorCode} - ${e.message}")
    
    // Handle specific service errors that couldn't be resolved.
    if (e.errorDetails?.errorCode == "ServiceQuotaExceededException" || 
        e.errorDetails?.errorCode == "ThrottlingException") {
        println("Rate limiting persisted - consider longer delays or quota increase")
    }
} catch (e: ClientException) {
    // Client-side errors (persistent network issues, DNS resolution failures, etc.)
    println("Client error after retries: ${e.message}")
}

Anpassen des Wiederholungsverhaltens

In den folgenden Abschnitten wird gezeigt, wie Sie das Wiederholungsverhalten des SDK an Ihren speziellen Anwendungsfall anpassen können.

Konfigurieren Sie die maximale Anzahl an Versuchen

Sie können die standardmäßige maximale Anzahl von Versuchen (3) im retryStrategyDSL-Block während der Client-Erstellung anpassen.

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        maxAttempts = 5
    }
}

Mit dem im vorherigen Snippet gezeigten DynamoDB-Serviceclient versucht das SDK API-Aufrufe, die fehlschlagen, bis zu fünf Mal (der erste Versuch plus vier Wiederholungen).

Sie können automatische Wiederholungsversuche vollständig deaktivieren, indem Sie die maximale Anzahl von Versuchen auf einen festlegen, wie im folgenden Codeausschnitt gezeigt.

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        maxAttempts = 1  // The SDK makes no retries.
    }
}

Konfigurieren Sie Verzögerungen und Backoff

Wenn ein Wiederholungsversuch erforderlich ist, wartet die standardmäßige Wiederholungsstrategie, bevor sie den nächsten Versuch durchführt. Die Verzögerung beim ersten Versuch ist gering, nimmt aber bei späteren Wiederholungen exponentiell zu. Die maximale Verzögerung ist begrenzt, sodass sie nicht zu groß wird.

Schließlich wird zufälliger Jitter auf die Verzögerungen zwischen allen Versuchen angewendet. Der Jitter trägt dazu bei, die Auswirkungen großer Flotten zu mildern, die zu erneuten Stürmen führen können. (Weitere Informationen zu exponentiellem Backoff und Jitter finden Sie in diesem AWS Architektur-Blogbeitrag.)

Die Verzögerungsparameter sind im DSL-Block konfigurierbar. delayProvider

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        delayProvider {
            initialDelay = 100.milliseconds
            maxBackoff = 5.seconds
        }
    }
}

Bei der im vorherigen Codeausschnitt gezeigten Konfiguration verzögert der Client den ersten Wiederholungsversuch um bis zu 100 Millisekunden. Die maximale Zeitspanne zwischen jedem Wiederholungsversuch beträgt 5 Sekunden.

Die folgenden Parameter sind für die Optimierung von Verzögerungen und Backoff verfügbar.

Parameter	Standardwert	Beschreibung
initialDelay	10 Millisekunden	Die maximale Verzögerung für den ersten Wiederholungsversuch. Wenn Jitter angewendet wird, kann die tatsächliche Verzögerung geringer sein.
jitter	1,0 (voller Jitter)	Die maximale Amplitude, um die die berechnete Verzögerung nach dem Zufallsprinzip reduziert werden soll. Der Standardwert 1,0 bedeutet, dass die berechnete Verzögerung auf einen beliebigen Wert von bis zu 100% reduziert werden kann (z. B. auf 0). Ein Wert von 0,5 bedeutet, dass die berechnete Verzögerung um bis zu die Hälfte reduziert werden kann. Somit könnte eine maximale Verzögerung von 10 ms auf einen Wert zwischen 5 ms und 10 ms reduziert werden. Ein Wert von 0,0 bedeutet, dass kein Jitter angewendet wird. Wichtig ️ Die Jitter-Konfiguration ist eine erweiterte Funktion. Eine Anpassung dieses Verhaltens wird normalerweise nicht empfohlen.
maxBackoff	20 Sekunden	Die maximale Verzögerung, die für jeden Versuch gelten soll. Wenn Sie diesen Wert festlegen, wird das exponentielle Wachstum zwischen aufeinanderfolgenden Versuchen begrenzt und verhindert, dass das berechnete Maximum zu groß ist. Dieser Parameter begrenzt die berechnete Verzögerung, bevor Jitter angewendet wird. Wenn er angewendet wird, kann Jitter die Verzögerung noch weiter reduzieren.
scaleFactor	1.5	Die exponentielle Basis, um die nachfolgende maximale Verzögerung erhöht wird. Bei einem Wert initialDelay von 10 ms und einem Wert scaleFactor von 1,5 würden beispielsweise die folgenden maximalen Verzögerungen berechnet: Wiederholung 1:10 ms × 1,5° = 10 ms Wiederholung 2:10 ms × 1,5¹ = 15 ms Wiederholung 3:10 ms × 1,5² = 22,5 ms Wiederholungsversuch 4:10 ms × 1,5³ = 33,75 ms Wenn Jitter angewendet wird, kann der tatsächliche Betrag jeder Verzögerung geringer sein.

Konfigurieren Sie den Token-Bucket für Wiederholungsversuche

Sie können das Verhalten der standardmäßigen Wiederholungsstrategie weiter ändern, indem Sie die Standardkonfiguration des Token-Buckets anpassen. Der Token-Bucket für Wiederholungen trägt dazu bei, Wiederholungsversuche zu reduzieren, bei denen die Erfolgswahrscheinlichkeit geringer ist oder deren Behebung mehr Zeit in Anspruch nehmen könnte, wie z. B. Timeout- und Drosselungsfehler.

Wichtig

Die Token-Bucket-Konfiguration ist eine erweiterte Funktion. Das Anpassen dieses Verhaltens wird normalerweise nicht empfohlen.

Bei jedem erneuten Versuch (optional einschließlich des ersten Versuchs) wird die Kapazität des Token-Buckets um einen Teil verringert. Der dekrementierte Betrag hängt von der Art des Versuchs ab. Beispielsweise kann es billig sein, vorübergehende Fehler erneut zu versuchen, aber die Wiederholung von Timeout- oder Drosselungsfehlern kann teurer sein.

Ein erfolgreicher Versuch gibt dem Bucket wieder Kapazität zurück. Der Bucket darf nicht über seine maximale Kapazität hinaus erhöht und auch nicht unter Null reduziert werden.

Je nach Wert der useCircuitBreakerMode Einstellung führen Versuche, die Kapazität unter Null zu reduzieren, zu einem der folgenden Ergebnisse:

• Wenn die Einstellung TRUE ist, wird eine Ausnahme ausgelöst, z. B. wenn zu viele Wiederholungen stattgefunden haben und es unwahrscheinlich ist, dass weitere Versuche erfolgreich sind.

• Wenn die Einstellung FALSE ist, kommt es zu einer Verzögerung, z. B. zu Verzögerungen, bis der Bucket wieder ausreichend Kapazität hat.

Anmerkung

Wenn der Schutzschalter aktiviert wird (der Token-Bucket erreicht die Kapazität Null), gibt das SDK eine Meldung ClientException mit der Meldung „Kapazität erneut versuchen überschritten“ aus. Dies ist eine clientseitige Ausnahme, keineAwsServiceException, da sie eher auf die Wiederholungslogik des SDK als auf den Service zurückzuführen ist. AWS Die Ausnahme wird sofort ausgelöst, ohne dass der Vorgang versucht wird, wodurch Wiederholungsversuche bei Dienstausfällen vermieden werden.

Die Token-Bucket-Parameter sind im tokenBucketDSL-Block konfigurierbar:

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        tokenBucket {
            maxCapacity = 100
            refillUnitsPerSecond = 2
        }
    }
}

Die folgenden Parameter sind für die Optimierung des Retry-Token-Buckets verfügbar:

Parameter	Standardwert	Beschreibung
initialTryCost	0	Der Betrag, der bei ersten Versuchen aus dem Bucket herabgesetzt werden soll. Der Standardwert 0 bedeutet, dass keine Kapazität verringert wird und somit die ersten Versuche nicht gestoppt oder verzögert werden.
initialTrySuccessIncrement	1	Der Betrag, um den die Kapazität erhöht werden soll, wenn der erste Versuch erfolgreich war.
maxCapacity	500	Die maximale Kapazität des Token-Buckets. Die Anzahl der verfügbaren Token darf diese Anzahl nicht überschreiten.
refillUnitsPerSecond	0	Die Menge an Kapazität, die dem Bucket jede Sekunde wieder hinzugefügt wird. Ein Wert von 0 bedeutet, dass keine Kapazität automatisch wieder hinzugefügt wird. (Beispielsweise führen nur erfolgreiche Versuche zu einer Erhöhung der Kapazität). Ein Wert von 0 useCircuitBreakerMode muss TRUE sein.
retryCost	5	Der Betrag, der bei einem Versuch nach einem vorübergehenden Ausfall aus dem Bucket herabgesetzt werden soll. Wenn der Versuch erfolgreich ist, wird derselbe Betrag wieder zurück in den Bucket inkrementiert.
timeoutRetryCost	10	Der Betrag, der bei einem Versuch nach einem Timeout oder einem Drosselungsfehler vom Bucket heruntergerechnet werden soll. Wenn der Versuch erfolgreich ist, wird derselbe Betrag wieder auf den Bucket erhöht.
useCircuitBreakerMode	TRUE	Bestimmt das Verhalten, wenn ein Versuch, die Kapazität zu verringern, dazu führen würde, dass die Kapazität des Buckets unter Null fällt. Bei TRUE löst der Token-Bucket eine Ausnahme aus, die angibt, dass keine Wiederholungskapazität mehr vorhanden ist. Bei FALSE verzögert der Token-Bucket den Versuch, bis genügend Kapazität wieder aufgefüllt ist.

Ausführliche Informationen zu Ausnahmetypen, die bei Wiederholungsszenarien ausgelöst werden, einschließlich Ausnahmen bei Leistungsschaltern, finden Sie unter. Welche Ausnahmen erreichen Ihren Code, wenn Wiederholungsversuche fehlschlagen

Konfigurieren Sie adaptive Wiederholungsversuche

Als Alternative zur standardmäßigen Wiederholungsstrategie ist die adaptive Wiederholungsstrategie ein fortschrittlicher Ansatz, bei dem nach der idealen Anforderungsrate gesucht wird, um Drosselungsfehler zu minimieren.

Wichtig

Adaptive Wiederholungen sind ein erweiterter Wiederholungsmodus. Die Verwendung dieser Wiederholungsstrategie wird normalerweise nicht empfohlen.

Adaptive Wiederholungen umfassen alle Funktionen von Standardwiederholungen. Es fügt einen clientseitigen Ratenbegrenzer hinzu, der die Rate gedrosselter Anfragen im Vergleich zu Anfragen ohne Drosselung misst. Außerdem wird der Datenverkehr so begrenzt, dass versucht wird, innerhalb einer sicheren Bandbreite zu bleiben, sodass im Idealfall keine Drosselungsfehler auftreten.

Die Rate passt sich in Echtzeit an sich ändernde Betriebsbedingungen und Verkehrsmuster an und kann die Verkehrsrate entsprechend erhöhen oder verringern. Entscheidend ist, dass der Ratenbegrenzer erste Versuche in Szenarien mit hohem Verkehrsaufkommen verzögern kann.

Sie wählen die adaptive Wiederholungsstrategie aus, indem Sie der Methode einen zusätzlichen Parameter hinzufügen. retryStrategy Die Parameter des Ratenbegrenzers sind im rateLimiterDSL-Block konfigurierbar.

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy(AdaptiveRetryStrategy) {
        maxAttempts = 10
        rateLimiter {
            minFillRate = 1.0
            smoothing = 0.75
        }
    }
}

Anmerkung

Bei der adaptiven Wiederholungsstrategie wird davon ausgegangen, dass der Client mit einer einzelnen Ressource arbeitet (z. B. einer DynamoDB-Tabelle oder einem Amazon S3 S3-Bucket).

Wenn Sie einen einzelnen Client für mehrere Ressourcen verwenden, führen Drosselungen oder Ausfälle im Zusammenhang mit einer Ressource zu einer erhöhten Latenz und zu Ausfällen, wenn der Client auf alle anderen Ressourcen zugreift. Wenn Sie die Strategie der adaptiven Wiederholung verwenden, empfehlen wir, für jede Ressource einen einzelnen Client zu verwenden.