Práticas recomendadas para latência de solicitação e tratamento de erros

Esta página descreve as práticas recomendadas para otimizar a latência da solicitação e processar erros na API Cloud Healthcare. Implemente essas práticas ao planejar e projetar a arquitetura do sistema.

O Google oferece um contrato de nível de serviço (SLA) que define o tempo de atividade esperado do serviço da API Cloud Healthcare e como os clientes podem lidar com erros. Para mais informações, consulte o Contrato de nível de serviço (SLA) do Cloud Healthcare.

Implementar a lógica de repetição e os timeouts

Para lidar com atrasos e erros causados por solicitações com falha, implemente a lógica de repetição e os tempos limite adequados. Ao definir a duração do tempo limite, permita tempo suficiente para fazer o seguinte:

• Deixe a API Cloud Healthcare processar a solicitação.
• Determine se o erro foi originado pelo serviço ou pelo cliente.

É possível repetir algumas tentativas, mas outras não podem ser repetidas e persistem em várias tentativas. Por exemplo, se os dados da solicitação estiverem formatados incorretamente, o servidor vai responder com um código de status 400 Bad Request. A solicitação não vai ser concluída até que você corrija os dados.

Para lidar com essas situações, você precisa planejar os estados de erro finais.

Para mais informações sobre a lógica de nova tentativa e os tempos limite, consulte Repetir solicitações com falha.

Processar erros em várias camadas

Quando o middleware interage com a API Cloud Healthcare, implemente a lógica de nova tentativa e os tempos limite no cliente e no middleware. Se um cliente encontrar erros após o limite de novas tentativas, você precisará identificar se o erro ocorreu no cliente, no middleware ou no serviço da API Cloud Healthcare. Isso é especialmente importante ao planejar estados de erro finais.

Pense no seguinte cenário:

1. O middleware recebe um erro 500 Internal Server Error da API Cloud Healthcare ao enviar uma solicitação.
2. A camada de middleware tenta a solicitação mais cinco vezes, alcançando o limite e parando de tentar.
3. O cliente recebe um erro 500 Internal Server Error final.

É importante entender que o erro originou-se na API Cloud Healthcare, não no middleware. Para simplificar a depuração, forneça essas informações no erro retornado ao cliente.

O diagrama a seguir mostra um cenário em que um proxy de middleware recebe erros 500 Internal Server Error ao encaminhar uma solicitação de um cliente para a API Cloud Healthcare. O cliente e o proxy implementam tratamento de erros e as novas tentativas.

Figura 1. As camadas em que você precisa implementar a lógica de nova tentativa e os tempos limite são o cliente e o proxy.

A Figura 1 mostra as seguintes etapas:

1. O cliente envia uma solicitação válida para a API Cloud Healthcare por um proxy de middleware.
2. O proxy encaminha a solicitação para a API Cloud Healthcare.
3. A API Cloud Healthcare retorna um erro 500 Internal Server Error para o proxy. O proxy tenta a solicitação mais cinco vezes até que o limite de tentativas seja atingido.

4. O proxy retorna o estado final de erro, 500 Internal Server Error, ao cliente.

   Usando as recomendações mostradas anteriormente, é possível depurar o estado final de erro fazendo com que o proxy retorne o seguinte erro para o cliente:

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

   Adicione mais informações sobre o erro retornado pela API Cloud Healthcare.

Às vezes, o cliente ou proxy recebe erros 500 Internal Server Error após os limites de nova tentativa e não pode tentar novamente. Nesse caso, uma pessoa pode precisar intervir para diagnosticar se o erro veio do proxy ou da API Cloud Healthcare.

Escolher quais erros tentar novamente

Dependendo da arquitetura do sistema, é possível tentar novamente determinados erros e ignorar outros. Confira a seguir uma lista não exaustiva de códigos de erro da API Cloud Healthcare que podem ser tentados novamente:

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

Esses erros geralmente não ocorrem com a mesma frequência, e alguns podem nunca ocorrer.

Efeitos da arquitetura do sistema

A arquitetura do sistema influencia como e quando você tenta corrigir erros.

Por exemplo, em uma arquitetura direta de cliente para servidor, um cliente que recebe um erro 401 UNAUTHENTICATED da API Cloud Healthcare pode fazer uma nova autenticação e tentar novamente a solicitação.

Suponha que um sistema tenha uma camada de middleware entre o cliente e a API Cloud Healthcare. Se o cliente tiver feito a autenticação corretamente e um token de autenticação expirado tiver causado o problema, o middleware precisará atualizar o token e tentar a solicitação novamente.

Depois de analisar os estados finais de erro, você pode ajustar os erros que o cliente tenta novamente com base nas suas descobertas.

Planejar estados de erro finais

Mesmo após a implementação da lógica de nova tentativa e dos tempos limite, um cliente ou middleware pode receber erros até que as novas tentativas sejam esgotadas. O último erro retornado antes que as novas tentativas e os tempos limite sejam esgotados é o estado de erro final. Você pode encontrar um estado de erro final para erros de consistência de dados.

Às vezes, um estado de erro final exige intervenção humana. Tente implementar uma solução para resolver o estado final de erro de uma solicitação. Caso contrário, registre o estado final do erro para que uma pessoa possa analisá-lo.

Considere o seguinte ao planejar como processar os estados de erro finais:

• Se há dependências de processamento que precisam ser interrompidas se uma transação ou um pacote do FHIR não puder ser concluído.
• Se muitas instâncias de máquina virtual (VM) começarem a falhar permanentemente, um cliente precisará informar as solicitações que falharam. Depois que o problema for corrigido, o cliente precisará tentar as solicitações novamente.
• O monitoramento, os sistemas de alerta e os objetivos de nível de serviço (SLOs) são necessários para garantir a estabilidade do sistema. Consulte Testar e monitorar para mais informações.

Planejar para aumentar a latência

A API Cloud Healthcare é um serviço escalonável e com bom desempenho, mas a latência da solicitação ainda pode variar pelos seguintes motivos:

• Pequenas diferenças entre solicitações, mesmo que pareçam insignificantes, podem causar tempo de processamento extra.
• Solicitações semelhantes podem ter latências diferentes. Por exemplo, duas solicitações semelhantes que adicionam um registro ao armazenamento de dados podem ter latências diferentes se uma delas ultrapassar um limite que aciona uma tarefa extra, como alocar mais armazenamento.
• A API Cloud Healthcare processa muitas solicitações simultaneamente. O momento em que um cliente envia uma solicitação, medido em frações de segundo, pode coincidir com um momento em que a API Cloud Healthcare está sob uma carga mais pesada do que o normal.
• Se um recurso físico da API Cloud Healthcare, como um disco, estiver processando muitas solicitações, ele precisará concluir as tarefas em fila antes de processar outras solicitações.
• Às vezes, a API Cloud Healthcare tenta novamente erros no servidor, o que pode aumentar a latência para os clientes.
• Pode haver várias cópias de dados em diferentes data centers em um local regional ou multirregional. Se suas solicitações forem roteadas por vários data centers, na solicitação original ou em uma nova tentativa, a latência pode aumentar.

Planejar usando a latência de percentil

Para planejar o aumento da latência, analise a latência de percentil das suas solicitações. Os exemplos a seguir descrevem a latência do 50º percentil e a latência do 99º percentil:

• A latência do 50º percentil é a latência máxima, em segundos, das 50% das solicitações mais rápidas. Por exemplo, se a latência do 50º percentil for de 0,5 segundo, a API Cloud Healthcare vai processar 50% das solicitações em 0,5 segundo. A latência do 50º percentil também é chamada de "latência mediana".
• A latência do 99º percentil é a latência máxima, em segundos, das 99% das solicitações mais rápidas. Por exemplo, se a latência do 99º percentil for de dois segundos, a API Cloud Healthcare vai processar 99% das solicitações em dois segundos.

Se você analisar a latência de percentil em um intervalo em que a API Cloud Healthcare processou apenas algumas solicitações, ela pode não ser útil ou indicativa da performance geral, porque solicitações fora da curva podem ter uma grande influência.

Por exemplo, suponha que um processo na API Cloud Healthcare processe 100 solicitações em 100 minutos. A latência do 99º percentil dos 100 minutos seria baseada na única solicitação mais lenta. Uma medição de latência usando uma única solicitação não é suficiente para entender se há problemas de performance.

Coletar uma amostra de solicitações maior em um período mais longo, como 24 horas, pode fornecer mais informações sobre o comportamento geral do sistema. Use esses exemplos para determinar como o sistema responde a um tráfego intenso.