Práticas recomendadas para operações de longa duração

Nesta página, descrevemos as práticas recomendadas para executar e gerenciar operações de longa duração (LROs, na sigla em inglês) na API Cloud Healthcare. Para uma visão geral das LROs na API Cloud Healthcare, consulte Como gerenciar operações de longa duração.

Propriedades da LRO

As seções a seguir se aplicam aos métodos listados em Métodos que retornam uma LRO.

Impacto na cota

As LROs não compartilham cotas com os métodos de criação, leitura, atualização e exclusão (CRUD, na sigla em inglês) da API Cloud Healthcare que consomem os seguintes tipos de cota:

A cota de LRO é calculada usando as métricas fhir_store_lro_ops e dicom_store_lro_ops.

A API Cloud Healthcare limita o número de LROs que podem ser executadas simultaneamente em um projeto do Google Cloud. Para mais informações, consulte Limites no número de LROs.

Capacidade de processamento de dados

Os métodos LRO geralmente alcançam uma capacidade de dados maior do que os métodos CRUD equivalentes. Por exemplo, a importação de instâncias DICOM com dicomStores.import normalmente tem um desempenho melhor do que armazenar as instâncias individualmente com dicomStores.storeInstances.

A execução de várias LROs simultaneamente pode não aumentar a capacidade de dados devido às seguintes restrições, especialmente ao processar grandes volumes de dados:

  • Limitações de cota
  • Contenção de recursos
  • Outro tráfego que o projeto do Google Cloud envia para a API Cloud Healthcare enquanto uma LRO é executada

Para uma capacidade máxima de dados ao executar LROs, considere o seguinte:

  • Pequenos lotes de importação e exportação normalmente têm baixa capacidade de processamento devido à sobrecarga.
  • As LROs executam e consomem a cota separadamente de outras operações da API Cloud Healthcare.
  • Cada LRO tem uma capacidade máxima de processamento.
  • LROs simultâneas no mesmo recurso podem causar contenção de bloqueio.
  • A API Cloud Healthcare limita o número de LROs que podem ser executadas simultaneamente em um projeto do Google Cloud. Para mais informações, consulte Limites no número de LROs.

Planeje o número de LROs necessários para seu caso de uso. Se você precisar particionar grandes lotes de dados em várias LROs, tente manter o número de partições baixo.

Integridade referencial de FHIR

O método fhirStores.import não considera a configuração disableReferentialIntegrity. Isso permite importar dados com interdependências arbitrárias que não exigem ordenação ou agrupamento, o que aumenta a capacidade de dados. Se os dados de entrada contiverem referências inválidas ou se alguns recursos FHIR não forem importados, o estado do armazenamento FHIR poderá violar a integridade referencial.

Para usar fhirStores.import, seu aplicativo cliente precisa garantir que as referências de recursos FHIR sejam válidas verificando o seguinte:

  • Os dados e a formatação do recurso FHIR estão corretos
  • Qualquer erro ocorrido durante a importação é gerenciado

Para aplicar a integridade referencial, use fhir.create ou fhir.executeBundle em vez de fhirStores.import. Para mais informações, consulte Como importar dados FHIR versus executar pacotes.

Notificações do Pub/Sub

Alguns métodos da API Cloud Healthcare enviam notificações do Pub/Sub para eventos clínicos, como a criação ou exclusão de um recurso de saúde. Para uma lista de métodos que enviam notificações do Pub/Sub, consulte Como configurar notificações do Pub/Sub.

Os métodos de importação a seguir não enviam notificações do Pub/Sub:

Se partes do seu aplicativo exigirem uma notificação quando uma importação for concluída, use outro método de notificação que possa listar os dados na importação.

Limites de tratamento de erros

A API Cloud Healthcare pode não registrar todos os erros em uma LRO, especialmente se ela processar grandes volumes de dados e produzir muitos erros. Implemente uma maneira de rastrear o processamento e os erros de LRO separadamente. Para mais informações, consulte Tratamento de erros de recursos.

Indexação de dados e pesquisa

Podem ocorrer atrasos nos resultados da pesquisa devido à indexação assíncrona da pesquisa. Se uma LRO criar ou atualizar um recurso FHIR, poderá levar mais tempo até que as alterações estejam disponíveis nos resultados da pesquisa.

Por exemplo, uma pesquisa por recursos "Paciente" em um armazenamento de FHIR pode não retornar todos os resultados imediatamente após uma operação de importação de FHIR.

Ordem de execução

As LROs são programadas com base na disponibilidade de recursos do Google Cloud. A ordem em que as LROs são executadas e terminam pode não corresponder à ordem em que foram solicitadas.

Evitar pequenas solicitações de importação e exportação

Nesta seção, descrevemos as limitações da LRO ao processar pequenos volumes de dados.

As LROs retornadas das operações de importação e exportação ajudam a escalonar a capacidade de dados processando grandes quantidades de dados rapidamente e evitando picos de carga. Para armazenar pequenas quantidades de dados, use outra técnica em Práticas recomendadas de armazenamento de dados.

Limites para o número de LROs

A API Cloud Healthcare limita o número de LROs que podem ser executadas simultaneamente em um projeto do Google Cloud. O limite é baseado no seguinte:

  • O tipo de LRO.
  • A quantidade de recursos do Google Cloud alocados para a LRO. Isso se baseia no tamanho dos dados de entrada.

Se você executar muitas LROs, os limites de taxa da API Cloud Healthcare, produzirão erros e poderão reduzir a capacidade de LRO. A API Cloud Healthcare economiza automaticamente os recursos do Google Cloud para que o número de LROs permaneça dentro dos limites de recursos.

LROs são processos em segundo plano. Portanto, se a carga de LROs interferir em processos de maior prioridade, como operações CRUD, a API Cloud Healthcare poderá reduzir a capacidade de LRO. Isso garante que os processos de maior prioridade estejam disponíveis.

Sobrecarga de alocação e limpeza de recursos

Quando uma LRO é iniciada, a API Cloud Healthcare aloca recursos. Isso pode levar vários minutos porque a API Cloud Healthcare precisa fazer o seguinte:

  1. Inicie um processo de controle.
  2. Alocar workers de um pool.
  3. Determinar o tamanho dos dados de entrada.
  4. Comece a alocar trabalho em escala

Interromper e limpar uma LRO também pode levar vários minutos.

Devido à sobrecarga, uma LRO que processa uma pequena quantidade de dados pode passar a maior parte do tempo alocando pools de workers e limpando recursos.

Se você tiver muitas dessas LROs, talvez encontre uma capacidade de processamento de dados mais baixa porque é mais provável que atinja os limites de cota do projeto do Google Cloud.

Limites de solicitação de cota de LRO

Antes de solicitar mais cota de LRO, implemente as Práticas recomendadas de gerenciamento de cotas. Se você ainda precisar de mais cota, entre em contato com o Google Cloud Customer Care. Para fazer uma solicitação, consulte as Práticas recomendadas para solicitar cota adicional.

Talvez seja necessário aumentar a cota se os dados de entrada forem grandes. Por exemplo:

  • Você está importando instâncias DICOM que têm vários petabytes (PB) de tamanho.
  • Você está importando dezenas de bilhões de recursos FHIR.

Status da LRO e estados de falha

Quando você inicia uma LRO, a resposta contém um ID exclusivo. Você pode ver o status de uma LRO pesquisando seu ID. Depois que a LRO é concluída, ela tem um destes estados:

  • Concluído sem erros
  • Concluído com alguns erros
  • Falha ao concluir, mas é possível que tenha gerado uma saída parcial antes de falhar

O exemplo JSON a seguir descreve a resposta retornada quando uma LRO é concluída:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "METADATA_TYPE",
    "apiMethodName": "API_METHOD_NAME",
    "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL"
    "counter": {
      "success": "SUCCESS_COUNT",
      // If there were any failures, they display in the `failure` field.
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  // The `response` field only displays if there were no errors.
  "response": {
    "@type": 
    
  },
  // If there were any errors, an `error` field displays instead of a `response` field.
  // See Troubleshooting long-running operations for a list of response codes.
  "error": {
    "code": ERROR_CODE,
    "message": "DESCRIPTION",
    "details": [
      {
        "@type": "...",
        FIELD1: ...,
        ...
      }
    ]
  }
}

Para ver o status de uma LRO, listar LROs e cancelar eles, consulte Como gerenciar operações de longa duração.

Gerenciar status de LRO e estados de falha

Para gerenciar o status de LRO e os estados de falha, siga estas práticas recomendadas:

  • Consulte as LROs para saber o status delas e verificar quando elas forem concluídas. Para pesquisar uma LRO, chame repetidamente o método projects.locations.datasets.operations.get até que a operação seja concluída. Use um recuo entre cada solicitação de pesquisa. Por exemplo, pesquise a cada 10 segundos. Quando a resposta contém "done": true, isso significa que a LRO foi concluída.

  • Depois que uma LRO for concluída, verifique se a resposta contém um campo error. Se isso acontecer, determine se quer repetir a operação com base no seguinte:

    • O código de erro. Consulte Como solucionar problemas de LROs para ver códigos de erro e ações recomendadas.
    • O número de novas tentativas que já ocorreram.
    • O tempo entre o início da LRO e o momento em que o erro ocorreu. Por exemplo, se uma LRO que normalmente leva várias horas leva vários dias e não retornou um status de falha, convém a intervenção de uma pessoa. Para mais informações sobre quando a intervenção humana pode ser necessária, consulte Planejar os estados de erro finais.

    Para saber como repetir uma LRO, consulte Colocar uma LRO na fila.

  • Se você não estiver repetindo a LRO, consulte o campo metadata.counter.failure para ver se ocorreram erros em recursos específicos. Talvez seja possível processar os recursos individualmente. Para mais informações, consulte Como lidar com erros de recursos.

Gerenciar erros de recursos

Uma LRO pode terminar com erros. Os erros na resposta da LRO seguem o modelo de erro do Google Cloud. A resposta da LRO inclui um link para o Cloud Logging para mais informações.

Detalhes do erro de LRO

Os erros de LRO no Cloud Logging têm as seguintes propriedades:

  • O registro de erros do Cloud Logging não contém o ID da LRO. Use os campos operation.id e operation.producer para encontrar o status e os erros da LRO. Por exemplo, LROs invocadas usando o método projects.locations.datasets.fhirStores.import contêm import_fhir no campo operation.producer.

    Se várias LROs tiverem os mesmos operation.id e operation.producer, use os carimbos de data/hora createTime e endTime para identificar a LRO correta.

  • Nem todos os erros de LRO estão disponíveis no Cloud Logging. O campo metadata.counter.failure pode exceder o número de erros reais registrados pelos seguintes motivos:

    • Limitações de cota do Cloud Logging
    • Disponibilidade do serviço Cloud Logging
    • Limites de registro da LRO

    Por exemplo, se uma LRO importar 10 milhões de recursos FHIR e 50% deles tiverem erros de formatação, apenas algumas centenas ou alguns milhares de erros poderão ser registrados devido à limitação de taxa e às cotas do Cloud Logging.

    O número de erros registrados também varia de acordo com o tempo de execução da LRO enquanto encontra altas taxas de erro. Se a LRO for executada lentamente, talvez apareça mais erros no Cloud Logging porque os erros foram espalhados por muito tempo e não estavam sujeitos à limitação de taxa.

Efeitos da nova tentativa de uma LRO

Se uma LRO encontrar um erro e um aplicativo cliente tentar de novo automaticamente a operação com os mesmos dados, essa nova tentativa poderá causar mais erros.

Considere um cenário em que uma LRO fhirStores.import termina com erros porque alguns dos recursos FHIR que ela tentou importar eram inválidos. Tentar novamente de forma automática a importação com os mesmos dados pode gerar muitos erros 409 ALREADY_EXISTS porque alguns recursos FHIR foram importados na operação original. Se você consultar uma LRO e encontrar uma operação de criação com falha, não tente de novo automaticamente. Uma pessoa precisa revisar os erros 409 ALREADY_EXISTS.

Se uma nova tentativa for bem-sucedida, o campo metadata.counter.failure não incluirá erros de operações anteriores. Isso pode causar uma contagem incorreta de erros, porque a resposta da nova tentativa não inclui erros das tentativas anteriores.

Tentar novamente uma LRO

Se você tiver um pipeline de processamento do lado do cliente que detecta erros de LRO, não use o Cloud Logging. Conforme mostrado em Detalhes do erro da LRO, os registros de erro do Cloud Logging para LROs não são confiáveis e estão incompletos. Use as técnicas das seções a seguir.

Repetir operações de importação

Para detectar dados com falha na importação, compare os dados importados na API Cloud Healthcare com os dados de origem no Cloud Storage. É possível importar dados usando os seguintes métodos:

Use um identificador exclusivo, como um número de registro médico (MRN, na sigla em inglês) para um recurso de paciente FHIR, para comparar os dados.

Consulte Efeitos da repetição de uma LRO para ver as etapas a serem seguidas ao tentar novamente uma operação de importação.

Executar novamente uma importação pode recriar recursos excluídos anteriormente. Pense no seguinte cenário:

  1. Você tenta importar 1.000.000 de recursos FHIR. 50 mil recursos falham devido a erros de formatação.
  2. Você passou vários dias corrigindo os erros de formatação. Durante esse período, um paciente solicita que você remova os registros dele.
  3. Se você executar a importação novamente, correrá o risco de recriar os dados do paciente que você excluiu.

Repetir operações de exportação

Para detectar dados que não foram exportados para o BigQuery, escreva um script para comparar IDs exclusivos nos dados de origem com os dados exportados.

É possível exportar dados para o BigQuery usando os seguintes métodos:

Adicione à fila e gerencie LROs

Se você executar LROs que processam grandes volumes de dados para integração ou em uma programação regular, implemente as seguintes técnicas de enfileiramento de LRO:

  • Limite LROs simultâneas a um pequeno número, como 5. É possível ajustar esse limite dependendo do tamanho e dos tipos de LROs que você executa.
  • Monitore a conclusão da LRO. Se ocorrerem erros, reprograme a LRO ou resolva os erros separadamente no pipeline de processamento.

  • Resolva automaticamente os erros em Como lidar com erros de recursos quando possível.

    • Entenda o caso de uso de importações de FHIR para determinar se é necessário ignorar erros 409 ALREADY_EXISTS ou executar operações CRUD separadas para resolver os erros. Conforme mostrado nos detalhes do erro da LRO, alguns erros 409 ALREADY_EXISTS podem não ser registrados no Cloud Logging. Se o aplicativo depende de registros de erros, use uma das técnicas em Repetir uma LRO.

    • Para resolver alguns erros, enfileire uma LRO menor para os dados que encontraram os erros ou execute operações CRUD separadas.

    • Para resolver muitos erros, executar a LRO novamente pode ser a opção mais simples para garantir a consistência. Consulte Repetir operações de importação para conhecer os riscos de uma nova importação em dados excluídos.

  • Detecte automaticamente se é necessária intervenção humana para corrigir erros. Ter ferramentas e manuais operacionais para administradores do sistema. As tarefas para corrigir erros podem incluir:

    • Reprograme uma LRO.
    • Reprograme um subconjunto de dados de uma LRO anterior.
    • Examinar erros e lidar com elementos de dados individuais que encontraram erros. Essa tarefa só é possível quando é possível determinar que todos os erros na LRO foram registrados.

  • Determinar programações de LRO. É possível agendar LROs para evitar a execução em horários de pico, quando muitas operações CRUD estão em execução. Para mais informações, consulte Gerenciar cota para maximizar a capacidade de processamento de dados.

Monitorar e receber alertas

Crie e mantenha procedimentos para monitorar LROs e resolver alertas. Os alertas são causados principalmente por status de LRO e problemas de queueing. Os procedimentos devem abordar as seguintes situações:

  • LROs que tentam novamente mais vezes do que estão configuradas.
  • São problemas que exigem intervenção humana para resolver um subconjunto de erros. Por exemplo, se uma LRO falhar e o cliente não conseguir resolver os erros, provavelmente será necessária intervenção humana. Consulte Colocar na fila e gerenciar LROs para mais informações sobre como resolver problemas que exigem intervenção humana.
  • Filas que excedem um tamanho ou aumentam muito rapidamente.
  • requisitos de política não atendidos, como um problema de permissões ou configuração incorreta.
  • Verificações de consistência que mostram problemas sistêmicos em várias LROs. É possível ter várias LROs de desidentificação que esperam que os conjuntos de dados de origem e de destino tenham o mesmo número de recursos FHIR. Se houver uma discrepância que aumente ao longo do tempo, ela poderá indicar dados não processados.
  • Problemas de cota de LRO. Para mais informações, consulte Gerenciar cota para maximizar a capacidade de processamento de dados e Práticas recomendadas para o gerenciamento de cotas.