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 de LROs Na API Cloud Healthcare, consulte Como 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 a propriedade fhir_store_lro_ops e dicom_store_lro_ops métricas.

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 de LRO geralmente atingem uma capacidade de processamento de dados maior ou 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 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 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 que seu caso de uso exige. 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 fhirStores.import método não considera a disableReferentialIntegrity do ambiente. 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 contiver referências inválidas ou se alguns recursos do FHIR não forem importados, o FHIR estado do repositório pode violar integridade referencial.

Para usar fhirStores.import, seu aplicativo cliente precisa para 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 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 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 um a importação terminar, use outro método de notificação que possa listar os dados em durante a importação.

Limites de tratamento de erros

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

Indexação de dados e pesquisa

Podem ocorrer atrasos nos resultados da pesquisa devido à indexação assíncrona da pesquisa. 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. O pedido em que as LROs são executadas e concluídas podem não corresponder à ordem em que foram solicitados.

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

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

LROs retornados das operações de importação e exportação ajudam a escalonar 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 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 o LRO. Isso se baseia do 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 taxa de transferência de LROs. A API Cloud Healthcare automaticamente preserva os recursos do Google Cloud para que o número de LROs permaneça dentro os limites de recursos.

LROs são processos em segundo plano. Portanto, se a carga interfira em processos de maior prioridade, como CRUD a API Cloud Healthcare, a API Cloud Healthcare pode reduzir a LRO e aumentar a capacidade de processamento. 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. Alocar workers de um pool.
  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 de solicitação de cota de LRO

Antes de solicitar mais cota de LRO, implemente o Práticas recomendadas para o 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 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 do FHIR.

Status da LRO e estados de falha

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

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

O exemplo de JSON a seguir descreve a resposta retornada quando uma solicitação termina em:

{
  "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 status de LRO e estados de falha

Para gerenciar o status de LRO e os estados de falha, 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, o 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 a operação será repetida com base no seguinte:

    • O código de erro. Consulte Como solucionar problemas de LROs para 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.

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

  • Se você não estiver tentando a LRO novamente, consulte o campo metadata.counter.failure para ver se ocorreram erros na 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 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, as LROs invocadas pelo 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 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 do Cloud Logging
    • Limites de registro de LRO

    Por exemplo, se uma LRO importar 10 milhões de recursos FHIR e 50% deles erros de formatação, apenas algumas centenas ou alguns milhares de erros podem 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 a LRO é executada quando encontra altas taxas de erro. Se a LRO for executada lentamente, pode mostrar mais erros no Cloud Logging porque os erros foram distribuídos por muito tempo e não estavam sujeitas à 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 pode 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 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. Como 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 o 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 da repetição de uma LRO para saber as etapas a serem seguidas e tentando uma operação de importação.

Executar novamente uma importação pode recriar recursos excluídos anteriormente. Considere este cenário:

  1. Você tenta importar 1.000.000 de recursos FHIR. 50.000 recursos falhar 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 a remoção dos registros dele.
  3. Se você executar a importação novamente, corre o risco de recriar os dados do paciente que que você excluiu.

Repetir operações de exportação

Para detectar os 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:

Enfileirar e gerenciar LROs

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

  • Limite as LROs simultâneas a um número pequeno, como 5. Você pode 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 o 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. Conforme mostrado nos detalhes do erro da LRO, alguns erros 409 ALREADY_EXISTS podem não ser registrados no Cloud Logging. Se seu aplicativo depende de registros de erros, use uma das técnicas em Tente fazer uma LRO novamente.

    • Para resolver alguns erros, coloque em fila um LRO dos dados que encontraram os erros ou realizar operações CRUD.

    • 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 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. Ter acesso a ferramentas e manuais operacionais para administradores de sistema. As tarefas para resolver erros podem incluir:

    • Reprograme uma LRO.
    • Reprograme 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 é possível determinar que todos os erros na LRO foram registrados.

  • Determinar programações 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 devem abordar as seguintes situações:

  • LROs que tentam novamente mais vezes do que o configurado.
  • 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 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 tamanho ou aumentam muito rapidamente.
  • Requisitos da política não atendidos, como um problema de permissões 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 os conjuntos de dados de origem e destino. tenham o mesmo número de recursos FHIR. Se houver uma discrepância que cresce 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.