Best practice per la latenza delle richieste e la gestione degli errori

In questa pagina vengono descritte le best practice per ottimizzare la latenza delle richieste e gestire gli errori nell'API Cloud Healthcare. Implementa queste pratiche mentre pianifichi e progetti l'architettura del sistema.

Google fornisce un accordo sul livello del servizio (SLA) che definisce l'uptime previsto del servizio API Cloud Healthcare e il modo in cui i client possono gestire gli errori. Per ulteriori informazioni, consulta l'accordo sul livello del servizio (SLA) di Cloud Healthcare.

Implementa la logica e i timeout per i nuovi tentativi

Per gestire i ritardi e gli errori causati da richieste non riuscite, implementa una logica di nuovo tentativo e timeout appropriati. Quando imposti la durata del timeout, concedi tempo sufficiente per eseguire le seguenti operazioni:

• Consenti all'API Cloud Healthcare di elaborare la richiesta.
• Determina se l'errore ha avuto origine dal servizio o dal client.

Puoi riprovare alcuni errori, ma altri non sono ripetibili e vengono mantenuti dopo più tentativi. Ad esempio, se i dati della richiesta non sono formattati correttamente, il server risponde con un codice di stato 400 Bad Request. La richiesta non avrà esito positivo finché non correggi i dati.

Per gestire queste situazioni, devi pianificare gli stati di errore finali.

Per saperne di più sulla logica di nuovo tentativo e sui timeout, consulta Riprovare le richieste non riuscite.

Gestire gli errori in più livelli

Quando il middleware interagisce con l'API Cloud Healthcare, implementa la logica di nuovo tentativo e i timeout nel client e nel middleware. Se un client riscontra errori che superano il limite di tentativi, devi essere in grado di identificare se l'errore si è verificato nel client, nel middleware o nel servizio API Cloud Healthcare sottostante. Questo aspetto è particolarmente importante quando si pianificano gli stati di errore finali.

Considera il seguente scenario:

1. Il middleware riceve un errore 500 Internal Server Error dall'API Cloud Healthcare durante l'invio di una richiesta.
2. Il livello middleware prova a ripetere la richiesta altre cinque volte, raggiungendo il limite, quindi smette di riprovare.
3. Il client riceve un errore 500 Internal Server Error finale.

È importante capire che l'errore ha avuto origine nell'API Cloud Healthcare, non nel middleware. Per semplificare il debug, fornisci queste informazioni nell'errore restituito al client.

Il seguente diagramma mostra uno scenario in cui un proxy middleware riceve errori 500 Internal Server Error quando inoltra una richiesta da un client all'API Cloud Healthcare. Sia il client che il proxy implementano la gestione degli errori e i nuovi tentativi.

Figura 1. I livelli in cui devi implementare la logica e i timeout per i nuovi tentativi sono il Client e il proxy.

La Figura 1 illustra i seguenti passaggi:

1. Il client invia una richiesta valida all'API Cloud Healthcare tramite un proxy middleware.
2. Il proxy inoltra la richiesta all'API Cloud Healthcare.
3. L'API Cloud Healthcare restituisce un errore 500 Internal Server Error al proxy. Il proxy riprova a inviare la richiesta altre cinque volte finché non viene raggiunto il limite di nuovi tentativi.

4. Il proxy restituisce al client lo stato di errore finale, 500 Internal Server Error.

   Utilizzando i suggerimenti mostrati in precedenza, puoi eseguire il debug dello stato di errore finale facendo in modo che il proxy restituisca al client il seguente errore:

   Error with underlying FHIR store in Cloud Healthcare API after 5 retries: 500 Internal Server Error

   Aggiungi altre informazioni sull'errore restituito dall'API Cloud Healthcare.

A volte, il client o il proxy riceve 500 Internal Server Error errori che superano i limiti relativi ai tentativi e non può riprovare. In questo caso, potrebbe essere necessario un intervento umano per diagnosticare se l'errore proviene dal proxy o dall'API Cloud Healthcare.

Scegli gli errori da riprovare

A seconda dell'architettura del sistema, puoi riprovare determinati errori e ignorarne altri. Di seguito è riportato un elenco non esaustivo di codici di errore dell'API Cloud Healthcare che è possibile eseguire nuovamente:

• 408 Request Timeout
• 425 Too Early
• 429 Too Many Requests
• 500 Internal Server Error
• 502 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Timeout

In genere questi errori non si verificano con la stessa frequenza e alcuni potrebbero non verificarsi mai.

Effetti dell'architettura di sistema

L'architettura del sistema influisce su come e quando ritenterai gli errori.

Ad esempio, in un'architettura client-to-server diretta, un client che riceve un errore 401 UNAUTHENTICATED dall'API Cloud Healthcare può eseguire nuovamente l'autenticazione e riprovare a eseguire la richiesta.

Supponiamo che un sistema abbia un livello middleware tra il client e l'API Cloud Healthcare. Se il client ha eseguito correttamente l'autenticazione e il problema è stato causato da un token di autenticazione scaduto, il middleware deve aggiornare il token e inviare nuovamente la richiesta.

Dopo aver analizzato gli stati di errore finali, puoi modificare gli errori che il client tenta di eseguire in base ai risultati.

Piano degli stati di errore finali

Anche dopo l'implementazione della logica dei nuovi tentativi e dei timeout, un client o un middleware potrebbero ricevere errori fino all'esaurimento dei nuovi tentativi. L'ultimo errore restituito prima dell'esaurimento di nuovi tentativi e timeout è lo stato di errore finale. Potresti riscontrare uno stato di errore finale per errori di coerenza dei dati.

A volte, uno stato di errore finale richiede un intervento umano. Prova a implementare una soluzione per risolvere lo stato di errore finale di una richiesta. In caso contrario, registra lo stato di errore finale in modo che una persona possa esaminarlo.

Tieni presente quanto segue durante la pianificazione della gestione degli stati di errore finali:

• Indica se sono presenti dipendenze di elaborazione che devono essere arrestate se una transazione o un bundle FHIR non riesce a completare correttamente.
• Se molte istanze di macchine virtuali (VM) iniziano a riscontrare errori definitivamente, un client deve segnalare le richieste non riuscite. Una volta risolto il problema, il client deve riprovare a eseguire le richieste.
• Il monitoraggio, i sistemi di avviso e gli obiettivi del livello del servizio (SLO) sono necessari per garantire la stabilità del sistema. Consulta Test e monitoraggio per ulteriori informazioni.

Pianifica una maggiore latenza

L'API Cloud Healthcare è un servizio scalabile ed efficiente, ma la latenza delle richieste può comunque variare per i seguenti motivi:

• Piccole differenze tra le richieste, anche se sembrano insignificanti, possono causare tempi di elaborazione aggiuntivi.
• Le richieste simili potrebbero avere latenze diverse. Ad esempio, due richieste simili che aggiungono un record all'archiviazione dei dati potrebbero avere latenze diverse se una supera una soglia che attiva un'attività aggiuntiva, come l'allocazione di più spazio di archiviazione.
• L'API Cloud Healthcare gestisce molte richieste contemporaneamente. Il momento in cui un client invia una richiesta, misurata in frazioni di secondo, potrebbe coincidere con un momento in cui l'API Cloud Healthcare è sotto un carico più pesante del solito.
• Se una risorsa fisica dell'API Cloud Healthcare, come un disco, gestisce molte richieste, deve completare le attività in coda prima di gestire altre richieste.
• A volte, l'API Cloud Healthcare prova a ripetere gli errori sul lato server, il che può aumentare la latenza per i client.
• Potrebbero essere presenti più copie dei dati in data center diversi in una località a una o più regioni. Se le tue richieste vengono instradate attraverso più data center, sulla richiesta originale o in occasione di un nuovo tentativo, la latenza potrebbe aumentare.

Piano utilizzando la latenza percentile

Puoi pianificare una maggiore latenza analizzando la latenza percentile delle richieste. I seguenti esempi descrivono la latenza del 50° percentile e la latenza del 99° percentile:

• La latenza al 50° percentile è la latenza massima, in secondi, per il 50% più rapido delle richieste. Ad esempio, se la latenza del 50° percentile è di 0,5 secondi, l'API Cloud Healthcare ha elaborato il 50% delle richieste entro 0,5 secondi. La latenza del 50° percentile è anche chiamata "latenza mediana".
• La latenza al 99° percentile è la latenza massima, in secondi, per il 99% delle richieste più rapido. Ad esempio, se la latenza del 99° percentile è di due secondi, l'API Cloud Healthcare ha elaborato il 99% delle richieste entro due secondi.

Se analizzi la latenza percentile in un intervallo in cui l'API Cloud Healthcare ha elaborato solo poche richieste, la latenza percentile potrebbe non essere utile o indicativa delle prestazioni complessive perché le richieste outlier possono avere una grande influenza.

Ad esempio, supponiamo che un processo nell'API Cloud Healthcare elabora 100 richieste in 100 minuti. La latenza del 99° percentile per i 100 minuti si basa sulla singola richiesta più lenta. Una misurazione della latenza utilizzando una singola richiesta non è sufficiente per comprendere se ci sono problemi di prestazioni.

La raccolta di un campione di richieste più ampio per un periodo di tempo più lungo, ad esempio 24 ore, può fornire maggiori informazioni sul comportamento generale del tuo sistema. Puoi utilizzare questi esempi per determinare in che modo il tuo sistema risponde al traffico intenso.