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

Questa pagina descrive le best practice per ottimizzare la latenza delle richieste e gestire gli errori nell'API Cloud Healthcare. Implementa queste pratiche durante la pianificazione e la progettazione dell'architettura del sistema.

Google fornisce un accordo sul livello del servizio (SLA) che definisce il tempo di attività previsto del servizio API Cloud Healthcare e la modalità di gestione degli errori da parte dei client. Per ulteriori informazioni, consulta l'Accordo sul livello del servizio (SLA) di Cloud Healthcare.

Implementa la logica per i nuovi tentativi e i timeout

Per gestire i ritardi e gli errori causati da richieste non riuscite, implementa la logica di ripetizione e i timeout appropriati. Quando imposti la durata del timeout, lascia un tempo sufficiente per svolgere le seguenti operazioni:

• Lascia che l'API Cloud Healthcare elabori la richiesta.
• Determina se l'errore ha avuto origine dal servizio o dal client.

Puoi riprovare per alcuni errori, ma altri non sono ripetibili e persistono 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 andrà a buon fine finché non avrai corretto i dati.

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

Per ulteriori informazioni sulla logica di ripetizione e sui timeout, consulta Riprovare le richieste non riuscite.

Gestire gli errori a più livelli

Quando il middleware interagisce con l'API Cloud Healthcare, implementa la logica di ripetizione e i timeout nel client e nel middleware. Se un client riscontra errori oltre 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 è 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 quando invia una richiesta.
2. Il livello middleware riprova la richiesta altre cinque volte, raggiunge il suo limite e poi smette di riprovare.
3. Il client riceve un errore 500 Internal Server Error finale.

È importante capire che l'errore è stato generato 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 durante l'inoltro di una richiesta da un client all'API Cloud Healthcare. Sia il client sia il proxy implementano la gestione degli errori e i tentativi di nuovo invio.

Figura 1. I livelli in cui devi implementare la logica di ripetizione e i timeout sono Client e Proxy.

La figura 1 mostra 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 la richiesta altre cinque volte fino a quando non viene raggiunto il suo limite di riprove.

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

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

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

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

A volte, il client o il proxy riceve errori 500 Internal Server Error dopo aver superato i limiti di ripetizione e non può più riprovare. In questo caso, potrebbe essere necessario l'intervento di un operatore per diagnosticare se l'errore proviene dal proxy o dall'API Cloud Healthcare.

Scegliere per quali errori riprovare

A seconda dell'architettura del sistema, puoi riprovare per determinati errori e ignorarne altri. Di seguito è riportato un elenco non esaustivo dei codici di errore dell'API Cloud Healthcare che possono essere sottoposti a ripetizione:

• 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 riprovare in caso di errori.

Ad esempio, in un'architettura client-to-server diretta, un client che riceve un errore 401 UNAUTHENTICATED dall'API Cloud Healthcare può autenticarsi di nuovo e riprovare a inviare la richiesta.

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

Dopo aver analizzato gli stati di errore finali, puoi modificare gli errori che il cliente ritenta in base ai risultati.

Pianifica gli stati di errore finali

Anche dopo aver implementato la logica di ripetizione e i timeout, un client o un middleware potrebbe ricevere errori fino a quando non sono stati esauriti i tentativi. L'ultimo errore restituito prima che i tentativi di recupero e i timeout siano esauriti è lo stato di errore finale. Potresti visualizzare un stato di errore finale per gli errori di coerenza dei dati.

A volte, uno stato di errore finale richiede l'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 quando pianifichi la gestione degli stati di errore finali:

• Indica se sono presenti dipendenze di elaborazione che devono essere interrotte se una transazione o un bundle FHIR non può essere completato correttamente.
• Se molte istanze di macchine virtuali (VM) iniziano a non riuscire definitivamente, un client deve segnalare le richieste non riuscite. Una volta risolto il problema, il cliente deve riprovare a inviare le richieste.
• Il monitoraggio, i sistemi di avviso e gli obiettivi del livello di servizio (SLO) sono necessari per garantire la stabilità del sistema. Per ulteriori informazioni, consulta Testa e monitora.

Pianifica un aumento della latenza

L'API Cloud Healthcare è un servizio scalabile e performante, 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.
• Richieste simili potrebbero avere latenze diverse. Ad esempio, due richieste simili che aggiungono un record allo spazio di archiviazione dei dati potrebbero avere latenze diverse se una supera una soglia che attiva un'attività aggiuntiva, ad esempio l'allocazione di più spazio di archiviazione.
• L'API Cloud Healthcare gestisce molte richieste contemporaneamente. Il momento in cui un client invia una richiesta, misurato in frazioni di secondo, potrebbe coincidere con un momento in cui l'API Cloud Healthcare è sotto un carico maggiore del solito.
• Se una risorsa fisica dell'API Cloud Healthcare, ad esempio un disco, gestisce molte richieste, deve completare le attività in coda prima di gestire altre richieste.
• A volte, l'API Cloud Healthcare riprova in caso di errori lato server, il che può aumentare la latenza per i client.
• Potrebbero esserci più copie dei dati in data center diversi in una località regionale o multiregionale. Se le richieste vengono inoltrate a più data center, sia nella richiesta originale sia in un nuovo tentativo, la latenza potrebbe aumentare.

Pianificare utilizzando la latenza percentile

Puoi prevedere un aumento della latenza analizzando la latenza percentile delle tue richieste. I seguenti esempi descrivono la latenza al 50° percentile e la latenza al 99° percentile:

• La latenza del 50° percentile è la latenza massima, in secondi, per il 50% delle richieste più rapide. Ad esempio, se la latenza del 50° percentile è di 0,5 secondi, l'API Cloud Healthcare ha elaborato il 50% delle richieste in 0,5 secondi. La latenza del 50° percentile è chiamata anche "latenza mediana".
• La latenza del 99° percentile è la latenza massima, in secondi, per il 99% delle richieste più rapide. 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 alcune richieste, la latenza percentile potrebbe non essere utile o indicativa del rendimento complessivo perché le richieste outlier possono avere un'influenza significativa.

Ad esempio, supponiamo che un processo nell'API Cloud Healthcare elabori 100 richieste in 100 minuti. La latenza del 99° percentile per 100 minuti si baserebbe sulla singola richiesta più lenta. Una misurazione della latenza che utilizza una singola richiesta non è sufficiente per capire se ci sono problemi di rendimento.

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