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

Nesta página, descrevemos as práticas recomendadas para otimizar a latência de 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 lógica de repetição e tempos limite

Para lidar com atrasos e erros causados por solicitações com falha, implemente lógica de repetição e 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 se originou do serviço ou do cliente.

É possível tentar novamente em alguns erros, mas outros não podem ser repetidos 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 será concluída até que você corrija os dados.

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

Para mais informações sobre a lógica de novas tentativas e 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 novas tentativas e tempos limite no cliente e no middleware. Se um cliente encontrar erros além do 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 fazer a solicitação mais cinco vezes, atingindo o limite, e depois para de tentar.
  3. O cliente recebe um erro 500 Internal Server Error final.

É importante entender que o erro teve origem 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 o tratamento de erros e as novas tentativas.

Diagrama de onde processar erros na pilha cliente/middleware/servidor.
Figura 1. As camadas em que você precisa implementar a lógica de novas tentativas 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 ao proxy. O proxy tenta de novo mais cinco vezes até atingir o limite de novas tentativas.

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

    Usando as recomendações mostradas anteriormente, é possível depurar o estado de erro final fazendo com que o proxy retorne o seguinte erro ao 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 além dos limites de novas tentativas e não pode tentar de novo. Nesse caso, talvez seja necessário que um humano intervenha 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 alguns erros e ignorar outros. Confira a seguir uma lista não exaustiva de códigos de erro da API Cloud Healthcare que podem ser repetidos:

  • 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 acontecer.

Efeitos de arquitetura do sistema

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

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

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

Depois de analisar os estados de erro finais, ajuste as novas tentativas do cliente com base nas suas descobertas.

Planejar estados de erro finais

Mesmo depois de implementar a lógica de novas tentativas e os tempos limite, um cliente ou middleware pode receber erros até que as novas tentativas se esgotem. O último erro retornado antes de novas tentativas e tempos limite serem 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 de erro final de uma solicitação. Caso contrário, registre o estado de erro final para que um humano possa revisar.

Considere o seguinte ao planejar como lidar com 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 com falha. Depois que o problema for corrigido, o cliente precisará tentar novamente.
  • Os sistemas de monitoramento e alertas 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 o aumento da latência

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

  • Pequenas diferenças entre solicitações, mesmo que pareçam insignificantes, podem causar um 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 cruzar 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 maior 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 na fila antes de processar outras solicitações.
  • Às vezes, a API Cloud Healthcare tenta novamente erros no lado do 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 as solicitações forem encaminhadas por vários data centers, na solicitação original ou em uma nova tentativa, pode haver aumento na latência.

Planejar usando a latência percentual

Para planejar um aumento na latência, analise a latência 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, de 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 processou 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, de 99% das solicitações mais rápidas. Por exemplo, se a latência do 99º percentil for de dois segundos, a API Cloud Healthcare processou 99% das solicitações em dois segundos.

Se você analisar a latência percentil em um intervalo em que a API Cloud Healthcare processou apenas algumas solicitações, a latência percentil pode não ser útil ou indicativa do desempenho geral, porque solicitações outliers 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 maior de solicitações em um período mais longo, como 24 horas, pode fornecer mais insights sobre o comportamento geral do seu sistema. Use essas amostras para determinar como seu sistema responde a um tráfego intenso.