Throttling di DynamoDB — perché succede e come risolverlo

Il throttling è DynamoDB che ti dice che hai toccato un limite — ma i limiti sono quattro, le eccezioni tre, e la soluzione per una causa ne peggiora un'altra. Alzare la capacità della tabella non serve a nulla contro una chiave calda; passare a on-demand non serve a nulla contro una chiave calda nemmeno lui, e può comunque andare in throttling secondo regole tutte sue. Questa guida è l'ombrello: quale limite hai davvero toccato, come le metriche li distinguono e la soluzione che corrisponde a ciascuna causa.

Perché DynamoDB manda le mie richieste in throttling?

Per uno di quattro motivi documentati: una singola partizione ha superato il suo limite fisso per partizione di 3.000 unità di lettura o 1.000 unità di scrittura al secondo (una chiave calda — succede in entrambe le modalità di capacità); la tabella ha superato le sue RCU/WCU provisionate (modalità Provisioned); l'account ha superato la quota di throughput a livello di region; oppure una tabella on-demand è cresciuta più in fretta del doppio del suo picco precedente entro 30 minuti. La soluzione dipende da quale dei quattro è stato, quindi diagnostica prima di ridimensionare qualsiasi cosa.

I quattro scenari di throttling

La pagina di troubleshooting di AWS divide il throttling in esattamente quattro casi:

1. Throughput del key-range (partizione) superato — entrambe le modalità. Ogni partizione è progettata per un massimo di 3.000 unità di lettura e 1.000 unità di scrittura al secondo (documentazione sulle partition key), e la dimensione degli item pesa su quel budget. Nessuna impostazione a livello di tabella lo alza; solo il design della chiave lo distribuisce. È il caso delle partizioni calde, e la tabella può sembrare enormemente sotto-utilizzata mentre va in throttling.
2. Throughput provisionato superato — modalità Provisioned. Il consumo ha battuto le RCU/WCU provisionate della tabella (o di una GSI), e il cuscinetto di ~5 minuti di burst capacity era esaurito. La scala di soluzioni sta dal lato capacità: auto scaling, una provisione più alta o un cambio di modalità.
3. Quota a livello di account superata. Le quote di account per region limitano il throughput totale — di default 40.000 unità di lettura e 40.000 di scrittura per tabella, e per la modalità Provisioned 80.000 RCU e 80.000 WCU per account (quote); sono valori di default iniziali, modificabili tramite Service Quotas, e le tabelle on-demand non hanno una quota di throughput a livello di account.
4. Throughput massimo on-demand superato. L'on-demand accoglie all'istante fino al doppio del picco precedente; cresci oltre il doppio entro 30 minuti e può andare in throttling (documentazione on-demand). Le nuove tabelle on-demand reggono 4.000 scritture/s e 12.000 letture/s appena create. Per un picco a gradino pianificato (un lancio, una promozione, una migrazione), pre-riscalda la tabella con il warm throughput invece di sperare che la rampa sia graduale.

Le tre eccezioni, e il campo che nomina la causa

• ProvisionedThroughputExceededException — throttling di capacità in modalità Provisioned: "you exceeded your maximum allowed provisioned throughput for a table or for one or more global secondary indexes". I dettagli sulla pagina d'errore dedicata.
• ThrottlingException — operazioni del control plane emesse troppo in fretta e, sulle tabelle on-demand, qualsiasi operazione del data plane la cui frequenza è troppo alta (è l'eccezione dietro la regola del doppio picco — vedi la pagina d'errore on-demand e ThrottlingException).
• RequestLimitExceeded — limiti di throughput a livello di account: territorio da "contact AWS Support", trattato sulla sua pagina d'errore.

Tutte e tre sono marcate come ritentabili, e tutte e tre ora portano valori strutturati di ThrottlingReason nella forma risorsa + operazione + limite — TableReadProvisionedThroughputExceeded, IndexWriteKeyRangeThroughputExceeded, TableWriteAccountLimitExceeded e così via (riferimento degli errori). Leggi la reason, non solo la classe dell'eccezione: nomina la risorsa (tabella o indice), la direzione dell'operazione e quale dei quattro limiti hai toccato — cioè esattamente la diagnosi. Una cautela che la documentazione stessa impone: le pagine AWS divergono sul fatto che il throttling da limite di account emerga come RequestLimitExceeded oppure come una ThrottlingException con reason AccountLimitExceeded, quindi aggancia la tua gestione alla stringa della reason.

Cosa assorbe il carico prima che tu vada in throttling

Due meccanismi integrati ammorbidiscono i limiti, e conoscerne i bordi spiega il "ieri funzionava":

• La burst capacity trattiene fino a cinque minuti (300 secondi) di capacità di lettura e scrittura inutilizzata per i picchi — ma DynamoDB può consumarla anche per manutenzione in background "without prior notice", e AWS annota esplicitamente che i dettagli possono cambiare. Non progettare sulla burst capacity; trattala come fortuna.
• La capacità adattiva sposta il throughput verso le partizioni calde in automatico e all'istante, e può isolare un item molto acceduto sulla propria partizione — ma solo "provided that traffic does not exceed your table's total provisioned capacity or the partition maximum capacity". Ribilancia lo squilibrio; non alza mai il tetto per partizione di 3.000/1.000, e non divide le collezioni di item quando la tabella ha una LSI. Le pagine di troubleshooting AWS attuali si appoggiano allo split-for-heat — le partizioni che si dividono sotto calore prolungato — che richiede tempo e non aiuta contro una singola chiave calda.

Diagnosticalo dalle metriche

CloudWatch separa le richieste dagli eventi, e la distinzione fa la diagnosi (riferimento delle metriche):

• ThrottledRequests conta una richiesta una volta sola se un qualsiasi evento al suo interno è andato in throttling — un PutItem su una tabella con tre GSI è una richiesta ma quattro eventi di scrittura. In un batch, si incrementa solo se ogni item è andato in throttling.
• ReadThrottleEvents / WriteThrottleEvents contano ogni singolo evento andato in throttling — un BatchGetItem di 10 item sono 10 eventi GetItem. Per vedere il throttling in scrittura di una GSI devi interrogare la metrica con TableName e GlobalSecondaryIndexName insieme — è così che la back-pressure della GSI si nasconde alle dashboard a livello di tabella.
• Le più recenti metriche di evento specifiche per reason (WriteProvisionedThroughputThrottleEvents, ReadKeyRangeThroughputThrottleEvents, …AccountLimitThrottleEvents, …MaxOnDemandThroughputThrottleEvents) suddividono i conteggi secondo le stesse quattro cause — se la tua region le espone, rispondono direttamente alla domanda "quale limite".

Una trappola: gli SDK ritentano automaticamente le richieste andate in throttling — la retry mode standard fa 3 tentativi in tutto di default (il rollout opt-in dei retry del 2026 porta i client DynamoDB a 4 tentativi con ritardi più stretti). Un throttling leggero quindi si manifesta come latenza, non come errori; guarda le metriche di throttling, non solo i log delle eccezioni.

Back-pressure della GSI: il throttling che punta alla tabella sbagliata

Se una GSI non riesce ad assorbire l'amplificazione delle scritture, "DynamoDB throttles writes to the base table to maintain data consistency" (documentazione sul throttling delle GSI) — anche quando alla tabella base la capacità avanza. Il ResourceArn dell'eccezione punta all'indice, ma l'operazione che è fallita è la tua scrittura sulla tabella base. Ogni indice ha bisogno del proprio piano di capacità (e della propria policy di auto scaling); perché una GSI limita le scritture sulla tabella base ne ripercorre la meccanica.

Abbina la soluzione alla causa

Fallo in DynoTable

La maggior parte del throttling autoinflitto parte da letture che costano più di quanto sembrino: uno Scan filtrato consuma comunque la lettura per intero. L'anteprima del costo prima dell'esecuzione di DynoTable mostra se uno statement diventa una Query o uno Scan, l'indice che colpisce e una stima del costo di lettura prima che tu lo spenda — la soluzione di throttling più economica è la lettura costosa che non hai eseguito. La guida Query vs Scan copre la differenza; il gratuito calcolatore della dimensione degli item trasforma un item reale nei numeri di RCU/WCU in cui sono misurati i limiti qui sopra.

Trappole e passi successivi

• I retry amplificano il sovraccarico. Il backoff è integrato negli SDK, ma un loop di retry stretto a livello applicativo sopra ai retry dell'SDK moltiplica la pressione proprio sulla partizione che è in difficoltà.
• I batch nascondono il throttling parziale. Un BatchWriteItem restituisce gli item non elaborati invece di sollevare un'eccezione finché qualche item riesce — controlla UnprocessedItems, non solo le eccezioni.
• La vista a livello di tabella mente sulle GSI. Traccia sempre gli eventi di throttling per indice; le dashboard della tabella base sembrano pulite durante la back-pressure.
• Le soluzioni di capacità richiedono minuti; il design della chiave è per sempre. L'auto scaling reagisce in ~5 minuti, gli aumenti di quota richiedono un ticket di supporto, ma una chiave calda ti segue in ogni modalità di capacità — investi lo sforzo dove si accumula: come funzionano le chiavi di partizione.

Scarica DynoTable per vedere il piano Scan-vs-Query e il costo di lettura di ogni query prima che venga eseguita contro la tua capacità.