Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Comportamento di ripetizione

Quando una richiesta ad an Servizio AWS fallisce a causa di un errore temporaneo o di una limitazione, l'SDK può riprovare automaticamente la richiesta. Questa pagina spiega come configurare i tentativi e come funzionano internamente.

Configurazione dei tentativi

Sei tu a controllare la strategia di ripetizione utilizzata dall'SDK e il numero di tentativi.

Scelta di una modalità di riprova

La modalità di riprova determina il comportamento dell'SDK quando una richiesta fallisce. Sono disponibili tre modalità: standard, adattiva e legacy.

Modalità standard (impostazione predefinita)

La modalità standard riprova le richieste non riuscite utilizzando un backoff esponenziale con jitter. Utilizza ritardi più brevi per gli errori transitori (come i timeout di rete) e ritardi più lunghi per gli errori di limitazione (ad esempio). ThrottlingException

La modalità standard include una quota di tentativi, un bucket di token che detrae i token per ogni tentativo e li reintegra quando le richieste hanno esito positivo. Quando i token disponibili sono esauriti, l'SDK restituisce l'errore senza riprovare, in modo che l'applicazione fallisca rapidamente invece di attendere tentativi che difficilmente avranno esito positivo. Ciò consente inoltre di risolvere più rapidamente le interruzioni del servizio riducendo il traffico dei tentativi di ripetizione. Durante il normale funzionamento, la quota rimane piena e non ha alcun effetto. La quota di tentativi non ritarda o blocca mai la richiesta iniziale. Sono interessati solo i tentativi. Per informazioni dettagliate, vedi Riprova la quota (token bucket).

Usa la modalità standard a meno che tu non abbia un motivo specifico per scegliere un'altra modalità.

Modalità adattiva

La modalità adattiva include tutto ciò che è in modalità standard, oltre a un limitatore di velocità lato client. Il limitatore di velocità tiene traccia delle risposte di limitazione e regola la frequenza con cui l'SDK invia le richieste. A differenza della modalità standard, la modalità adattiva può ritardare o bloccare la richiesta iniziale, non solo i tentativi, quando viene rilevata una limitazione.

Il limitatore di velocità funziona per istanza del client SDK. Tutte le richieste di un client condividono lo stesso limite di velocità, indipendentemente dall'operazione o dalla risorsa API a cui sono destinate.

Quando usare la modalità adattiva:

Quando non usare la modalità adattiva:

La modalità adattiva non è consigliata come impostazione predefinita generale.

Modalità Legacy

La modalità legacy è il comportamento di ripetizione utilizzato da ciascun SDK prima dell'introduzione della modalità standard. Non include una quota di tentativi standardizzata. Alcuni SDK (come Java) avevano le proprie implementazioni della quota di tentativi in modalità legacy, ma il comportamento non è coerente tra gli SDK. Senza una quota standardizzata, un cliente continua a riprovare a pieno ritmo durante le interruzioni del servizio. Ciò blocca i thread e le connessioni in caso di richieste che non hanno esito positivo, aggiungendo al contempo un carico che può ritardare il ripristino del servizio.

La modalità legacy varia a seconda degli SDK. Il numero di tentativi, i tempi di backoff, i set di errori rieseguibili e il comportamento di limitazione variano a seconda delle lingue. Il codice che dipende dal comportamento dei tentativi precedenti può comportarsi diversamente quando viene spostato tra gli SDK.

Disponibile in: Java, Python, Ruby, PHP, C++, CLI

Non disponibile in: .NET, Go, Kotlin, Rust, Swift, JavaScript

La modalità Legacy esiste per la compatibilità con le versioni precedenti. Se attualmente utilizzi la modalità legacy, passa alla modalità standard.

Riprova le impostazioni

Le seguenti impostazioni controllano il comportamento dei tentativi. È possibile impostarle tramite variabili di ambiente, il file di configurazione condiviso (~/.aws/config) o la configurazione del client in codice.

Un valore massimo di tentativi pari a 3 indica che l'SDK effettua una richiesta iniziale e fino a due tentativi. Imposta il numero massimo di tentativi per 1 disabilitare completamente i tentativi.

Precedenza di configurazione

Quando si specifica la stessa impostazione in più posizioni, l'SDK risolve il valore utilizzando la seguente precedenza, dalla più alta alla più bassa:

Segue la precedenza di configurazione standard dell'AWS SDK. Un valore impostato a un livello superiore sovrascrive sempre un valore impostato a un livello inferiore. Ad esempio, se si imposta AWS_RETRY_MODE=adaptive come variabile di ambiente e retry_mode=standard si attiva~/.aws/config, l'SDK utilizza la modalità adattiva.

Language-specific configurazione

Le impostazioni cross-SDK descritte in questa pagina (retry_modeemax_attempts) funzionano in tutti gli SDK. Tuttavia, l'API per la configurazione dei tentativi nel codice varia in base alla lingua. Consulta la guida per sviluppatori del tuo SDK per le opzioni di configurazione specifiche della lingua, ad esempio strategie di backoff personalizzate, ulteriori errori rieseguibili e ottimizzazione delle quote dei tentativi.

Come funzionano i tentativi

Questa sezione descrive come gli AWS SDK gestiscono le richieste non riuscite: quali errori innescano i nuovi tentativi, quanto tempo l'SDK attende tra un tentativo e l'altro e quando interrompe il ritentativo.

Cosa succede quando una richiesta fallisce

Quando si effettua una chiamata API tramite un AWS SDK, l'SDK segue questa sequenza:

L'SDK ripete questo ciclo finché la richiesta non ha esito positivo, viene raggiunto il numero massimo di tentativi, la quota di tentativi è esaurita o si verifica un errore non riutilizzabile. L'intero processo è automatico. La tua applicazione vede una risposta positiva o un errore finale.

Quali errori vengono ripetuti

L'SDK classifica ogni richiesta non riuscita in una delle tre categorie: transitoria, limitata o non riutilizzabile. Questa classificazione determina se l'SDK riprova la richiesta e quanto tempo attende prima di riprovare.

La classificazione si basa sul codice di errore e sul codice di stato HTTP nella risposta del servizio. Ad esempio, un HTTP 400 con il codice di errore RequestTimeout viene classificato come transitorio e ritentato. Un HTTP 400 with ValidationException è classificato come non ripetibile e viene restituito immediatamente.

Classificazione degli errori

Gli errori transitori vengono ritentati con un breve ritardo di base (50 ms):

Gli errori di limitazione vengono ritentati con un ritardo di base maggiore (1.000 ms):

Non-retryable gli errori (comeAccessDeniedException,ValidationException,ResourceNotFoundException) vengono restituiti immediatamente al codice.

Gli errori di limitazione indicano che il servizio ha rifiutato attivamente la tua richiesta a causa dei limiti di velocità, quindi l'SDK attende più a lungo prima di riprovare per dare al servizio il tempo di recuperare la capacità. Consulta i ritardi specificiQuanto dura l'SDK.

Quanto dura l'SDK

L'SDK utilizza il backoff esponenziale con jitter completo. In media, ogni nuovo tentativo attende più a lungo del precedente, con la randomizzazione per distribuire le richieste provenienti da più client.

Ritardi di base per tipo di errore

Il ritardo di base dipende dal fatto che l'errore sia transitorio o limitativo:

Formula di backoff

L'SDK calcola ogni ritardo tra i tentativi utilizzando questa formula:

delay = random(0, 1) × min(20,000 ms, base_delay × 2^retry)

Dove:

Il limite massimo di backoff è di 20 secondi. Nessun ritardo individuale supera i 20 secondi indipendentemente dal numero di tentativi effettuati.

Esempi funzionanti

Esempio 1: errore transitorio, massimo 3 tentativi

La latenza totale aggiunta è in media di circa 75 ms in entrambi i tentativi.

Esempio 2: errore di limitazione, massimo 3 tentativi

La latenza totale aggiunta è in media di circa 1.500 ms in entrambi i tentativi.

Esempio 3: errore transitorio, raggiungimento del limite di backoff

Con un ritardo base di 50 ms, il ritardo calcolato prima del limite sarebbe:

Il limite entra in vigore al decimo tentativo (11° tentativo) per gli errori transitori. Per gli errori di limitazione con una base di 1.000 ms, il limite ha effetto al sesto tentativo.

Perché il jitter è importante

Il moltiplicatore casuale si chiama full jitter. In caso contrario, tutti i client che riscontrano un errore contemporaneamente riproverebbero contemporaneamente, generando una raffica di traffico di tentativi (il problema del «thundering herd»). Il full jitter diffonde i tentativi in modo uniforme su tutta la finestra di backoff, in modo che il servizio riceva un flusso costante di richieste anziché picchi sincronizzati.

Ad esempio, supponiamo che 1.000 clienti ricevano tutti un 503 nello stesso momento. Il full jitter distribuisce i primi tentativi in modo uniforme su una finestra di 50 ms invece di avere tutti i 1.000 tentativi esattamente a 50 ms.

Server-directed tempistica dei nuovi tentativi

Alcune Servizi AWS includono un'x-amz-retry-afterintestazione nelle risposte di errore. Il valore dell'intestazione è un ritardo in millisecondi. Quando è presente questa intestazione, l'SDK utilizza il ritardo specificato dal server, limitato a un minimo del ritardo di backoff calcolato e a un massimo del ritardo di backoff calcolato più 5.000 ms. Poiché il backoff calcolato è a sua volta limitato a 20 secondi, il ritardo massimo effettivo diretto dal server è di 25 secondi. L'SDK non applica il jitter a questo valore, perché ci si aspetta che il servizio lo faccia. Ciò consente al servizio di comunicare esattamente quando prevede di avere capacità disponibile.

Riprova la quota (token bucket)

L'SDK mantiene un budget interno per i token che tiene traccia del rapporto tra richieste riuscite e fallimenti. Quando i guasti sono diffusi, il budget si esaurisce e l'SDK restituisce direttamente gli errori. L'applicazione fallisce rapidamente invece di attendere tentativi che difficilmente avranno esito positivo. Ciò riduce anche il traffico dei tentativi di ripetizione, aiutando a risolvere più rapidamente le interruzioni del servizio.

Come funziona la quota di tentativi

Il budget dei token inizia al completo. Ogni tentativo di nuovo tentativo detrae i token. Quando un nuovo tentativo ha esito positivo, l'SDK ripristina i token utilizzati da quel nuovo tentativo. Quando una richiesta ha esito positivo al primo tentativo (non sono necessari nuovi tentativi), l'SDK ripristina 1 token. Quando il budget raggiunge lo zero, l'SDK smette di riprovare e restituisce gli errori direttamente nel codice.

Il costo più elevato per i tentativi transitori riflette il loro diverso schema di errore. Gli errori transitori come 500s e gli errori di connessione spesso indicano un problema a livello di servizio. In queste situazioni, è improbabile che un nuovo tentativo abbia successo. Aumenta la latenza delle chiamate, limita le risorse del cliente e può ritardare il ripristino per tutti. Gli errori di limitazione indicano che il servizio ha bisogno di più tempo prima che la richiesta possa avere successo. L'SDK attende più a lungo tra un tentativo e l'altro per aumentare le probabilità di successo.

Quando viene eseguito il nuovo tentativo del blocco delle quote

La quota di tentativi tiene traccia dei token in ogni momento, ma blocca i tentativi solo quando il budget è esaurito. Durante il normale funzionamento, quasi tutte le richieste vengono soddisfatte e il budget rimane pieno. La quota non ha effetti osservabili sui nuovi tentativi.

Un nuovo tentativo riuscito ripristina solo il costo dei token (14 o 5 token), non il costo dei precedenti tentativi falliti nella stessa richiesta. Ad esempio, se il primo tentativo fallisce e il secondo va a buon fine, il budget perde 14 token netti. Il budget si esaurisce più rapidamente quando i tentativi esauriscono tutti i tentativi senza successo, ma si riduce anche gradualmente quando le richieste richiedono più tentativi prima di riuscire.

Con l'impostazione predefinita di un massimo di 3 tentativi, la quota inizia a diminuire quando più del 22% circa delle richieste comporta errori transitori prolungati o più del 32% circa in caso di errori di limitazione. Al di sotto di queste percentuali, le richieste riuscite rigenerano il budget più rapidamente di quanto i tentativi falliti lo esauriscano.

Il saldo iniziale del budget, pari a 500 token, fornisce un buffer in grado di assorbire brevi sequenze di errori. Un breve picco di errori, anche grave, non blocca i nuovi tentativi a meno che non persista abbastanza a lungo da esaurire il buffer.

Implicazioni pratiche

Service-specific comportamento

DynamoDB

I client DynamoDB utilizzano impostazioni predefinite ottimizzate per il profilo a bassa latenza di DynamoDB:

Queste impostazioni predefinite si applicano sia ad Amazon DynamoDB che a DynamoDB Streams.

Long-polling operazioni

Alcune AWS operazioni utilizzano polling lunghi. Possono tenere aperta una connessione in attesa dell'arrivo del lavoro. Queste operazioni ricevono un trattamento speciale di riprova:

Comportamento speciale: quando la quota di tentativi è esaurita e i tentativi vengono bloccati (passaggio 7Cosa succede quando una richiesta fallisce), l'SDK applica comunque un ritardo di backoff prima di restituire l'errore al codice.

Questo è importante perché le operazioni di polling prolungato vengono in genere eseguite in un ciclo ristretto. Il codice chiamaReceiveMessage, elabora tutti i messaggi, quindi richiama ReceiveMessage immediatamente di nuovo. Senza il backoff forzato, un budget di token esaurito farebbe sì che l'SDK restituisca errori senza ritardi. Il ciclo di polling invierebbe quindi immediatamente la richiesta successiva, aumentando l'utilizzo della CPU del client e generando traffico aggiuntivo. Il ritardo di backoff forzato interrompe questo ciclo, mantenendo gestibili l'utilizzo delle risorse del cliente e la frequenza di polling durante gli errori.

Supporto di AWS SDK e strumenti

La tabella seguente elenca la disponibilità del comportamento di ripetizione aggiornato in ogni SDK. Per SDK-specific informazioni dettagliate, tra cui la versione minima, le impostazioni predefinite relative al periodo precedente e successivo e gli esempi di codice, consulta il problema di tracciamento. GitHub