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 per applicazione. Le connessioni, sia HTTP che TCP, hanno come ambito l'istanza del client. La maggior parte degli ambienti di calcolo presenta limitazioni in termini di numero di connessioni che possono essere aperte contemporaneamente; inoltre, quando questi limiti vengono raggiunti, la connettività ne risentirà.

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.
  • 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 certa grado di errori potenziali in questi componenti implementando i criteri di ripetizione dei tentativi sulle risposte fornite dagli SDK.

L'applicazione deve effettuare nuovi tentativi in caso di errore?

La risposta breve è sì. Ma non è necessario effettuare nuovi tentativi 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 nuovi tentativi Riesecuzione degli SDK Descrizione
400 No No Richiesta non valida
401 No No Non autorizzato
403 Facoltativo No Non consentito
404 No No La risorsa non viene 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 è stata 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ì È possibile effettuare nuovi tentativi sul codice 429. Esaminare 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 compilando un problema di 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 dei tentativi nell'applicazione.

HTTP 403

Gli SDK di Azure Cosmos DB generalmente non effettuano nuovi tentativi in caso di errori HTTP 403, ma esistono alcuni errori associati a 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

Gli SDK di Azure Cosmos DB effettuano nuovi tentativi per gli errori HTTP 429 per impostazione predefinita 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 nuovo tentativo.

Quando si supera il numero di tentativi automatici consentiti dall'SDK, l'errore viene restituito all'applicazione. L'analisi ideale 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 utilizzare un algoritmo di back-off esponenziale o di configurare il client per aumentare il numero di tentativi per HTTP 429.

HTTP 449

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

Quando vengono superati i tentativi automatici dell'SDK, l'errore viene restituito all'applicazione. È possibile effettuare nuovi tentativi per gli 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 nuovi tentativi sul timeout e sui problemi di connettività tra i protocolli HTTP e TCP, se il nuovo tentativo è realizzabile:

  • Per le operazioni di lettura, gli SDK effettuano nuovi tentativi su qualsiasi timeout o errore relativo alla connettività.
  • Per le operazioni di scrittura, gli SDK non effettueranno nuovi tentativi 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 nuovo tentativo tra aree.

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

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

Dettagli di implementazione specifici per lingua

Per ottenere maggiori informazioni sui dettagli di implementazione relativi a una lingua, vedere:

Effettuare nuovi tentativi influisce sulla latenza?

Dal punto di vista del client, eventuali tentativi influiranno sulla latenza end-to-end di un'operazione. Quando la latenza P99 dell'applicazione è interessata, è necessario comprendere i tentativi che in esecuzione e come risolverli.

Gli SDK di Azure Cosmos DB forniscono informazioni dettagliate nei log e nella diagnostica che consentono di identificare i nuovi tentativi in esecuzione. Per ottenere maggiori informazioni, consultare 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 nuovi tentativi in un'altra area dell'account. Per comprendere 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 nuovi tentativi?L'applicazione copre tali tentativi?
  • 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 illustrati i documenti di risoluzione dei problemi correlati nella tabella precedente per escludere un problema nell'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