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

Esta página descreve 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 Gerenciar operações de longa duração.

Propriedades de LRO

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

Impacto na cota

Os LROs não compartilham a cota com os métodos de criar, ler, atualizar e excluir (CRUD) 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.

Taxa de transferência de dados

Os métodos LRO geralmente alcançam um throughput de dados maior do que os métodos CRUD equivalentes. Por exemplo, a importação de instâncias DICOM com dicomStores.import normalmente é 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:

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

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

  • Pequenos lotes de importação e exportação geralmente têm baixa taxa de transferência devido ao overhead.
  • As LROs são executadas e consomem cota separadamente de outras operações da API Cloud Healthcare.
  • Cada LRO tem uma taxa de transferência máxima.
  • 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 que seu caso de uso exige. Se você precisar particionar grandes lotes de dados em vários 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 dependências arbitrárias que não exigem ordenação ou agrupamento, o que aumenta a capacidade de dados. Se os dados de entrada tiverem referências inválidas ou se alguns recursos FHIR não forem importados, o estado da armazenagem FHIR poderá violar a integridade referencial.

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

  • Os dados e a formatação do recurso FHIR estão corretos
  • Todos os erros que ocorrem durante a importação são gerenciados

Para aplicar a integridade referencial, use fhir.create ou fhir.executeBundle em vez de fhirStores.import. Para mais informações, consulte Importar dados do FHIR em vez de 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 conferir 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 da importação.

Limites de tratamento de erros

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

Indexação de dados e pesquisas

Atrasos nos resultados da pesquisa podem ocorrer devido à indexação assíncrona. Se um LRO criar ou atualizar um recurso do FHIR, pode levar mais tempo para que as mudanças fiquem disponíveis nos resultados da pesquisa.

Por exemplo, uma pesquisa de recursos de 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 concluídas pode não corresponder à ordem em que foram solicitadas.

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

Esta seção descreve as limitações do LRO ao processar pequenos volumes de dados.

Os LROs retornados de operações de importação e exportação ajudam a dimensionar a capacidade de processamento 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 para 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 o LRO. Isso é baseado no tamanho dos dados de entrada.

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

As LROs são processos em segundo plano. Portanto, se a carga das LROs interferir em processos de prioridade mais alta, como operações CRUD, a API Cloud Healthcare poderá reduzir a taxa de transferência de LROs. Isso garante que os processos de maior prioridade estejam disponíveis.

Alocação de recursos e overhead de limpeza

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. Iniciar um processo de controlador.
  2. Aloque workers de um pool de workers.
  3. Determine o tamanho dos dados de entrada.
  4. Comece a alocar trabalho em grande escala.

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

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

Se você tiver muitas dessas LROs, poderá encontrar uma taxa de transferência de dados menor, porque é mais provável que atenda aos limites de cota do seu projeto do Google Cloud.

Limites para solicitar cota de LRO

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

Talvez você precise de mais cota se os dados de entrada forem grandes, por exemplo:

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

Status e estados de falha do LRO

Quando você inicia uma LRO, a resposta contém um ID exclusivo. É possível conferir o status de uma LRO pesquisando o ID dela. Depois que a LRO termina, ela tem um dos seguintes estados:

  • Concluída com sucesso, sem erros
  • Concluída com alguns erros
  • Falha ao concluir, mas possivelmente produziu uma saída parcial antes da falha

O exemplo de JSON abaixo 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 conferir o status de uma LRO, listar LROs e cancelar LROs, consulte Gerenciar operações de longa duração.

Gerenciar o status e os estados de falha do LRO

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

  • Consultar as LROs para saber o status 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, a LRO é concluída.

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

    • O código de erro. Consulte Solução de problemas de LROs para conferir 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, talvez seja necessário que um humano intervenha. Para mais informações sobre quando a intervenção humana pode ser necessária, consulte Planejar estados de erro finais.

    Consulte Colocar uma LRO na fila para informações sobre como repetir uma LRO.

  • Se você não estiver tentando novamente a LRO, confira o campo metadata.counter.failure para saber 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.

Processar erros de recursos

Uma LRO pode terminar com erros. Os erros na resposta do LRO seguem o modelo de erro do Google Cloud. A resposta da LRO inclui um link para o Cloud Logging com 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 do LRO. Use os campos operation.id e operation.producer para encontrar o status e os erros da LRO. Por exemplo, as LROs invocadas pelo método projects.locations.datasets.fhirStores.import contêm import_fhir no campo operation.producer.

    Se várias LROs tiverem o mesmo 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 devido aos seguintes motivos:

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

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

    O número de erros registrados também varia de acordo com o tempo de execução da LRO ao encontrar altas taxas de erros. Se a LRO for executada lentamente, ela poderá mostrar mais erros no Cloud Logging porque os erros foram espalhados por um longo período e não foram sujeitos a limitação de taxa.

Efeitos da nova tentativa de uma LRO

Se uma LRO encontrar um erro e um aplicativo cliente tentar automaticamente a operação usando os mesmos dados, a 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 a importação automaticamente com os mesmos dados pode gerar muitos erros 409 ALREADY_EXISTS porque alguns recursos do 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 novamente automaticamente. Uma pessoa precisa analisar os erros de 409 ALREADY_EXISTS.

Se uma nova tentativa tiver sucesso, o campo metadata.counter.failure não incluirá erros de operações anteriores. Isso pode causar uma contagem de erros incorreta, porque a resposta da nova tentativa bem-sucedida não inclui erros de 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 de LRO, os registros de erros do Cloud Logging para LROs são incompletos e não confiáveis. Use as técnicas nas seções a seguir.

Tentar novamente as operações de importação

Para detectar dados que não foram importados, 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 FHIR Patient, para comparar os dados.

Consulte Efeitos de uma nova tentativa de uma LRO para saber o que fazer ao repetir uma operação de importação.

A reexecução de uma importação pode recriar recursos que você excluiu anteriormente. Considere este cenário:

  1. Você tenta importar 1.000.000 recursos FHIR. 50.000 recursos falham devido a erros de formatação.
  2. Você passa 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, corre o risco de recriar os dados do paciente que foram excluídos.

Tentar novamente as operações de exportação

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

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

Enfileirar e gerenciar 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 LROs:

  • Limite as LROs simultâneas a um número pequeno, como 5. É possível ajustar esse limite dependendo do tamanho e dos tipos de LROs executados.
  • 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 das importações do FHIR para determinar se é necessário ignorar erros de 409 ALREADY_EXISTS ou realizar operações CRUD separadas para resolvê-los. Como mostrado em Detalhes do erro LRO, alguns erros 409 ALREADY_EXISTS podem não ser registrados no Cloud Logging. Se o aplicativo depender de registros de erros, use uma das técnicas em Repetir uma LRO.

    • Para resolver alguns erros, coloque uma LRO menor na fila para os dados que encontraram os erros ou realize operações CRUD separadas.

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

  • Detectar automaticamente se a intervenção humana é necessária para corrigir erros. Você precisa ter ferramentas e livros de operações para administradores de sistemas. As tarefas para resolver erros podem incluir:

    • Reprogramar uma LRO.
    • Reprogramar um subconjunto de dados de uma LRO anterior.
    • Examine os erros e resolva os elementos de dados individuais que encontraram erros. Essa tarefa só é possível se você puder determinar que todos os erros no LRO foram registrados.

  • Determinar os horários de LRO. Você pode programar 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 a cota para maximizar a taxa de transferência de dados.

Monitorar e receber alertas

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

  • LROs que tentam novamente mais vezes do que o configurado.
  • 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 uma intervenção humana. Consulte Enfileirar e gerenciar LROs para mais informações sobre como resolver problemas que exigem intervenção humana.
  • Filas que excedem um comprimento ou crescem muito rápido.
  • Os requisitos da política não estão sendo atendidos, como um problema de permissão ou uma configuração incorreta.
  • Verificações de consistência que mostram problemas sistêmicos em várias LROs. Você pode ter várias LROs de desidentificação que esperam que o conjunto de dados de origem e o de destino tenham o mesmo número de recursos do FHIR. Se houver uma discrepância que aumenta com o tempo, isso pode indicar dados não processados.
  • Problemas de cota de LRO. Para mais informações, consulte Gerenciar a cota para maximizar a taxa de transferência de dados e Práticas recomendadas para gerenciamento de cota.