Condividi tramite

Progettazione di applicazioni resilienti con SDK di Azure Cosmos DB

  • Articolo

SI APPLICA A: NoSQL

Quando si creano applicazioni client che interagiscono con Azure Cosmos DB tramite uno qualsiasi degli SDK, è importante comprendere alcuni concetti fondamentali. Questo articolo è una guida alla progettazione che consente di comprendere tali concetti fondamentali e progettare applicazioni resilienti.

Panoramica

Per ottenere una panoramica dei concetti illustrati in questo articolo, vedere il video seguente:

Modalità di connettività

Gli SDK di Azure Cosmos DB possono connettersi al servizio in due modalità di connettività. Gli SDK .NET e Java possono connettersi al servizio sia in modalità gateway che in modalità direct, mentre gli altri possono connettersi solo in modalità gateway. La modalità gateway utilizza il protocollo HTTP mentre la modalità direct generalmente usa il protocollo TCP.

La modalità gateway viene sempre usata per recuperare i metadati, come account, contenitore e informazioni di routing, indipendentemente dalla modalità di utilizzo in cui è stato configurato l'SDK. Queste informazioni vengono memorizzate nella cache e vengono usate per connettersi alle repliche del servizio.

In sintesi, per gli SDK in modalità gateway, è possibile prevedere il traffico HTTP, mentre per gli SDK in modalità direct è possibile prevedere una combinazione di traffico HTTP e TCP in circostanze diverse, ad esempio inizializzazione, recupero di metadati o informazioni di routing.

Istanze e connessioni client

Indipendentemente dalla modalità di connettività, è fondamentale mantenere un'istanza Singleton del client SDK per account e per applicazione. Le connessioni, sia HTTP che TCP, hanno come ambito l'istanza client. La maggior parte degli ambienti di calcolo presenta limitazioni in termini di numero di connessioni che è possibile aprire contemporaneamente; inoltre, quando questi limiti vengono raggiunti, la connettività ne risente.

Applicazioni e reti distribuite

Quando si progettano applicazioni distribuite, sono disponibili tre componenti chiave:

  • L'applicazione e l'ambiente in cui viene eseguita.
  • La rete, che include qualsiasi componente tra l'applicazione e l'endpoint del servizio Azure Cosmos DB.
  • L'endpoint del servizio Azure Cosmos DB.

Quando si verificano errori, spesso rientrano in una di queste tre aree ed è importante comprendere che, a causa della natura distribuita del sistema, è poco pratico prevedere il 100% di disponibilità per uno qualsiasi di questi componenti.

Azure Cosmos DB dispone di un set completo di contratti di servizio di disponibilità, ma nessuno di essi possiede il 100% di disponibilità. I componenti di rete che connettono l'applicazione all'endpoint del servizio possono presentare problemi hardware temporanei e perdere pacchetti. Anche l'ambiente di calcolo in cui viene eseguita l'applicazione potrebbe avere un picco di CPU che influisce sulle operazioni. Queste condizioni di errore possono influire sulle operazioni degli SDK e in genere vengono rilevate come errori con codici specifici.

L'applicazione deve essere resiliente a un certo grado di errori potenziali in questi componenti implementando i criteri di ripetizione sulle risposte fornite dagli SDK.

L'applicazione deve effettuare un retry in caso di errore?

La risposta breve è sì. Ma non è necessario consigliabile effettuare retry per tutti gli errori: alcuni codici di errore o di stato non sono temporanei. La seguente tabella fornisce un elenco dettagliato:

Codice di stato È consigliabile aggiungere retry Retry degli SDK Descrizione
400 No No Richiesta non valida
401 No No Non autorizzato
403 Facoltativo No Non consentito
404 No No Risorsa non trovata
408 Sì Sì Timeout della richiesta
409 No No L'errore di conflitto si verifica quando l'identità fornita (ID e chiave di partizione) per una risorsa in un'operazione di scrittura è stata eseguita da una risorsa esistente o quando è stato violato un vincolo di chiave univoco.
410 Sì Sì Eccezioni non riuscite (errore temporaneo che non deve violare il contratto di servizio)
412 No No L'errore di precondizione si verifica quando l'operazione ha specificato un eTag diverso dalla versione disponibile nel server. Si tratta di un errore di concorrenza ottimistica. Riprovare a eseguire la richiesta dopo aver letto la versione più recente della risorsa e aver aggiornato l'ETag sulla richiesta.
413 No No Entità della richiesta troppo grande
429 Sì Sì In case di errore 429, è possibile effettuare un retry in sicurezza. Consultare la guida per risolvere i problemi relativi a HTTP 429.
449 Sì Sì Si tratta di un errore temporaneo che si verifica solo nelle operazioni di scrittura ed è possibile eseguire nuovi tentativi in sicurezza. Questo errore può segnalare un problema di progettazione in cui troppe operazioni simultanee provano ad aggiornare lo stesso oggetto in Azure Cosmos DB.
500 No No Impossibile eseguire l'operazione a causa di un errore imprevisto del servizio. Contattare il supporto inoltrando un problema al supporto tecnico di Azure.
503 Sì Sì Servizio non disponibile

Nella tabella precedente, tutti i codici di stato contrassegnati con Sì nella seconda colonna devono avere un certo grado di copertura di retry nell'applicazione.

HTTP 403

Gli SDK di Azure Cosmos DB generalmente non effettuano retry in caso di errori HTTP 403, ma esistono alcuni errori associati ad HTTP 403 a cui l'applicazione potrebbe decidere di reagire. Ad esempio, se viene visualizzato un errore che indica che una chiave di partizione è completa, è possibile decidere di modificare la chiave di partizione del documento che si sta tentando di scrivere in base a una regola aziendale.

HTTP 429

Per impostazione predefinita, gli SDK di Azure Cosmos DB effettuano retry per errori HTTP 429 seguendo la configurazione del client e rispettando l'intestazione della del servizio x-ms-retry-after-ms, che attende il tempo indicato per poi effettuare un retry.

Quando si supera il numero di retry consentiti dall'SDK, l'errore viene restituito all'applicazione. Idealmente, l'analisi dell'intestazione x-ms-retry-after-ms nella risposta può essere usata come suggerimento per decidere quanto tempo attendere prima di ritentare la richiesta. Un'altra alternativa è quella di usare un algoritmo di back-off esponenziale o di configurare il client per aumentare il numero di retry per errori HTTP 429.

HTTP 449

Gli SDK di Azure Cosmos DB effettuano retry su HTTP 449 con un back-off incrementale durante un periodo di tempo fisso, in modo da soddisfare la maggior parte degli scenari.

Quando vengono superati i tentativi automatici dell'SDK, l'errore viene restituito all'applicazione. È possibile effettuare retry per errori HTTP 449 in sicurezza. A causa della natura estremamente simultanea delle operazioni di scrittura, è preferibile avere un algoritmo di back-off casuale per evitare di ripetere lo stesso livello di concorrenza dopo un intervallo fisso.

I timeout di rete e gli errori di connettività sono tra gli errori più comuni. Gli SDK di Azure Cosmos DB sono di per sé resilienti ed effettuano retry sul timeout e sui problemi di connettività tra i protocolli HTTP e TCP, se è realizzabile un'operazione di retry:

  • Per le operazioni di lettura, gli SDK effettuano retry su qualsiasi timeout o errore relativo alla connettività.
  • Per le operazioni di scrittura, gli SDK non effettueranno retry perché queste operazioni non sono idempotenti. Quando si verifica un timeout in attesa della risposta, non è possibile sapere se la richiesta ha raggiunto il servizio.

Se l'account dispone di più aree disponibili, gli SDK effettueranno anche un retry tra aree.

A causa della natura dei timeout e degli errori di connettività, questi potrebbero non essere visualizzati all'interno delle metriche dell'account , poiché coprono solo gli errori che si verificano sul lato servizio.

È consigliabile che le applicazioni dispongano di criteri di ripetizione per questi scenari e prendano in considerazione la risoluzione dei timeout di scrittura. Ad esempio, un retry effettuato in caso di timeout di creazione può restituire un errore HTTP 409 (conflitto) se la richiesta precedente ha raggiunto il servizio; in caso contrario, il retry avrà esito positivo.

Dettagli di implementazione specifici per lingua

Per acquisire ulteriori dettagli di implementazione relativi a una lingua, vedere:

I retry influiscono sulla latenza?

Dal punto di vista del client, eventuali retry influiranno sulla latenza end-to-end di un'operazione. Se è interessata la latenza P99 dell'applicazione, è importante capire quali retry sono in esecuzione e come risolverli.

Gli SDK di Azure Cosmos DB forniscono informazioni dettagliate nei log e nella diagnostica che consentono di identificare i retry in esecuzione. Per ulteriori informazioni, vedere come raccogliere la diagnostica di .NET SDK e come raccogliere la diagnostica di Java SDK.

Le interruzioni regionali possono essere interessate?

Gli SDK di Azure Cosmos DB coprono la disponibilità a livello di area e possono effettuare retry in un'altra area dell'account. Per capire quali sono gli scenari che coinvolgono altre aree, consultare l'articolo Scenari di ripetizione dei tentativi e configurazioni in ambienti multidimensionali.

Quando contattare il servizio clienti

Prima di contattare il servizio clienti, seguire questa procedura:

  • Qual è l'impatto misurato in volume delle operazioni interessate rispetto alle operazioni completate correttamente? Rientra nei contratti di servizio?
  • La latenza P99 è interessata?
  • Gli errori sono legati ai codici di errore su cui l'applicazione deve effettuare retry? L'applicazione copre tali retry?
  • Gli errori interessano tutte le istanze dell'applicazione o solo un sottoinsieme? I problemi ridotti a un sottoinsieme di istanze in genere sono correlati a tale istanze.
  • Sono stati consultati i documenti di risoluzione dei problemi illustrati nella tabella precedente per escludere un problema all'ambiente dell'applicazione?

Se tutte le istanze dell'applicazione sono interessate o la percentuale di operazioni interessate non rientra nei contratti di servizio o influisce sui contratti di servizio dell'applicazione e su P99, contattare il servizio clienti.

Passaggi successivi