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 l'uptime previsto del servizioAPI Cloud HealthcareI 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.

Implementare la logica di ripetizione e i timeout

Per gestire ritardi ed errori causati da richieste non riuscite, implementa timeout e logica di ripetizione appropriati. Quando imposti la durata del timeout, lascia un tempo sufficiente per svolgere 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 a risolvere alcuni errori, ma altri non sono riprovare e persistono in 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 pianificare gli stati di errore finali.

Per ulteriori informazioni sulla logica di ripetizione e sui timeout, vedi 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 dopo aver superato 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. Ciò è particolarmente importante quando pianifichi 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, 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 durante l'inoltro di una richiesta da un client all'API Cloud Healthcare. Il client e il proxy implementano la gestione degli errori e i tentativi.

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 finché non viene raggiunto il limite di tentativi.

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

   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 ulteriori informazioni sull'errore restituito dall'API Cloud Healthcare.

A volte, il client o il proxy riceve errori 500 Internal Server Error oltre i limiti di nuovi tentativi e non può 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 gli errori da riprovare

A seconda dell'architettura del sistema, puoi riprovare a correggere alcuni errori e ignorarne altri. Di seguito è riportato un elenco non esaustivo dei codici di errore dell'API Cloud Healthcare per cui è possibile riprovare:

• 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 vengono riprovati gli errori.

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

Supponiamo che un sistema abbia un livello middleware tra il client e l'API Cloud Healthcare. Se il client si è autenticato correttamente e il problema è 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 client ritenta in base ai risultati.

Pianificare gli stati di errore finali

Anche dopo l'implementazione della logica di ripetizione e dei timeout, un client o un middleware potrebbe ricevere errori fino all'esaurimento dei tentativi. L'ultimo errore restituito prima che i tentativi e i timeout siano esauriti è lo stato di errore finale. Potresti riscontrare uno 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 possa essere esaminato da una persona.

Quando pianifichi la gestione degli stati di errore finali, tieni presente quanto segue:

• Se esistono dipendenze di elaborazione che devono essere interrotte se una transazione FHIR o un bundle non possono essere completati correttamente.
• Se molte istanze di macchine virtuali (VM) iniziano a non funzionare in modo permanente, un client deve segnalare le richieste non riuscite. Dopo aver risolto il problema, il client deve riprovare a inviare le richieste.
• I sistemi di monitoraggio e avviso e gli obiettivi del livello di servizio (SLO) sono necessari per garantire la stabilità del sistema. Per ulteriori informazioni, consulta la sezione Test e monitoraggio.

Pianificare l'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 un tempo di elaborazione aggiuntivo.
• Richieste simili potrebbero avere latenze diverse. Ad esempio, due richieste simili che aggiungono un record all'archiviazione dati potrebbero avere latenze diverse se una supera una soglia che attiva un'attività aggiuntiva, come l'allocazione di ulteriore 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 è sottoposta a 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 a risolvere gli errori lato server, il che può aumentare la latenza per i client.
• Potrebbero esserci più copie dei dati in diversi data center in una località regionale o multiregionale. Se le richieste vengono instradate su più data center, nella richiesta originale o in un nuovo tentativo, potrebbe verificarsi un aumento della latenza.

Pianificare utilizzando la latenza percentile

Puoi pianificare l'aumento della latenza analizzando la latenza percentile delle tue richieste. Gli esempi seguenti descrivono la latenza del 50° percentile e la latenza del 99° percentile:

• La latenza del 50° percentile è la latenza massima, in secondi, per il 50% più veloce 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 è chiamata anche "latenza mediana".
• La latenza del 99° percentile è la latenza massima, in secondi, per il 99% più veloce delle richieste. 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 elabori 100 richieste in 100 minuti. La latenza del 99° percentile per i 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.

La raccolta di 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 campioni per determinare in che modo il sistema risponde al traffico elevato.