Como funciona o cache de chamadas

Para usar o cache de chamadas, você cria um cache de execução e o configura para ter um local Amazon S3 associado aos dados em cache. Ao iniciar uma execução, você especifica o cache de execução. Um cache de execução não é dedicado a um fluxo de trabalho. As execuções de vários fluxos de trabalho podem usar o mesmo cache.

Durante a fase de exportação de uma execução, o sistema exporta as saídas concluídas da tarefa para o local do Amazon S3. Para exportar arquivos de tarefas intermediárias, declare esses arquivos como saídas de tarefas na definição do fluxo de trabalho. O cache de chamadas também salva internamente os metadados e cria hashes exclusivos para cada entrada do cache.

Para cada tarefa em execução, o mecanismo de fluxo de trabalho detecta se há uma entrada de cache correspondente para essa tarefa. Se não houver nenhuma entrada de cache correspondente, HealthOmics calcula a tarefa. Se houver uma entrada de cache correspondente, o mecanismo recuperará os resultados em cache.

Para combinar as entradas do cache, HealthOmics usa o mecanismo de hash incluído nos mecanismos de fluxo de trabalho nativos. HealthOmicsestende essas implementações de hash existentes para contabilizar HealthOmics variáveis, como S3 ETags e resumos de contêineres ECR.

HealthOmics oferece suporte ao cache de chamadas para essas versões de linguagem do fluxo de trabalho:

• Versões WDL 1.0, 1.1 e a versão de desenvolvimento

• Nextflow versões 23.10 e 24.10

• Todas as versões do CWL

nota

HealthOmics não oferece suporte ao cache de chamadas para fluxos de trabalho do Ready2Run.

Modelo de responsabilidade compartilhada

Há uma responsabilidade compartilhada entre os usuários de determinar AWS se tarefas e execuções são boas candidatas para o armazenamento em cache de chamadas. O cache de chamadas alcança os melhores resultados quando todas as tarefas são idempotentes (execuções repetidas de uma tarefa usando as mesmas entradas produzem os mesmos resultados).

No entanto, se uma tarefa incluir elementos não determinísticos (como gerações de números aleatórios ou hora do sistema), execuções repetidas da tarefa usando as mesmas entradas podem resultar em saídas diferentes. Isso pode afetar a eficácia do armazenamento em cache de chamadas das seguintes formas:

• Se HealthOmics usar uma entrada de cache (criada por uma execução anterior) que não seja idêntica à saída que a execução da tarefa produziria para a execução atual, a execução poderá gerar resultados diferentes da mesma execução sem armazenamento em cache.

• HealthOmics pode não encontrar uma entrada de cache correspondente para uma tarefa que deva corresponder, devido às saídas de tarefas não determinísticas. Se não encontrar a entrada de cache válida, a execução recomputará desnecessariamente a tarefa, o que reduz os benefícios de economia de custos do uso do cache de chamadas.

A seguir estão os comportamentos de tarefas conhecidos que podem causar resultados não determinísticos que afetam os resultados do cache de chamadas:

• Usando geradores de números aleatórios.

• Dependência da hora do sistema.

• Usando a concorrência (condições de corrida podem causar variação na saída).

• Buscar arquivos locais ou remotos além do especificado nos parâmetros de entrada da tarefa.

Para outros cenários que podem causar comportamento não determinístico, consulte Entradas de processo não determinísticas no site de documentação do Nextflow.

Se você suspeitar que uma tarefa produz resultados não determinísticos, considere usar os recursos do mecanismo de fluxo de trabalho, como a exclusão de cache no Nextflow, para evitar o armazenamento em cache de tarefas específicas que não são determinísticas.

Recomendamos que você analise minuciosamente seus requisitos específicos de fluxo de trabalho e tarefas antes de ativar o cache de chamadas em qualquer ambiente em que o cache de chamadas ineficaz ou saídas diferentes do esperado possam apresentar riscos. Por exemplo, as possíveis limitações do armazenamento em cache de chamadas devem ser cuidadosamente consideradas para determinar se o cache de chamadas é apropriado para casos de uso clínico.

Requisitos de armazenamento em cache para tarefas

HealthOmics armazena em cache as saídas de tarefas que atendem aos seguintes requisitos:

• A tarefa deve definir um contêiner. HealthOmics não armazenará em cache as saídas de uma tarefa sem contêiner.

• A tarefa deve produzir uma ou mais saídas. Você especifica as saídas da tarefa na definição do fluxo de trabalho.

• A definição do fluxo de trabalho não deve usar valores dinâmicos. Por exemplo, se você passar um parâmetro para uma tarefa com um valor que aumenta a cada execução, HealthOmics não armazena em cache as saídas da tarefa.

nota

Se várias tarefas em uma execução usarem a mesma imagem de contêiner, HealthOmics fornecerá a mesma versão de imagem para todas essas tarefas. Depois de HealthOmics extrair a imagem, ela ignora todas as atualizações na imagem do contêiner durante a execução. Essa abordagem fornece uma experiência previsível e consistente e evita possíveis problemas que possam surgir de atualizações na imagem do contêiner que são implantadas no meio da execução.

Execute o desempenho do cache

Ao ativar o cache de chamadas para uma execução, você pode observar os seguintes impactos no desempenho da execução:

• Durante a primeira execução, HealthOmics salva os dados do cache para as tarefas na execução. Você pode ter tempos de exportação mais longos para essa execução, porque o cache de chamadas aumenta a quantidade de dados de exportação.

• Em execuções subsequentes, ao retomar uma execução do cache, isso pode reduzir o número de etapas de processamento e reduzir o tempo de execução.

• Se você também optar por declarar arquivos intermediários como saídas, o tempo de exportação poderá ser ainda maior, pois esses dados podem ser mais detalhados.

Eventos de retenção e invalidação de dados em cache

O objetivo principal de um cache de execução é otimizar o cálculo das tarefas na execução. Se houver uma entrada de cache correspondente válida para uma tarefa, HealthOmics use a entrada de cache em vez de recalcular a tarefa. Caso contrário, HealthOmics reverte para o comportamento padrão do serviço, que é recalcular a tarefa e suas tarefas dependentes. Ao usar essa abordagem, falhas de cache não fazem com que a execução falhe.

Recomendamos que você gerencie o tamanho do cache de execução. Com o tempo, as entradas de cache podem não ser mais válidas devido às atualizações do mecanismo de fluxo de trabalho ou do HealthOmics serviço ou devido às alterações feitas na execução ou nas tarefas de execução. As seções a seguir fornecem detalhes adicionais.

Tópicos

• Atualizações de versões do manifesto e atualização de dados

• Comportamento do cache de execução

• Controle o tamanho do cache de execução

Atualizações de versões do manifesto e atualização de dados

Periodicamente, o HealthOmics serviço pode introduzir novos recursos ou atualizações do mecanismo de fluxo de trabalho que invalidam algumas ou todas as entradas de cache de execução. Nessa situação, suas execuções podem sofrer uma única perda de cache.

HealthOmics cria um arquivo de manifesto JSON para cada entrada de cache. Para execuções iniciadas após 12 de fevereiro de 2025, o arquivo de manifesto inclui um parâmetro de versão. Se uma atualização de serviço invalidar qualquer entrada de cache, HealthOmics incrementa o número da versão para que você possa identificar as entradas de cache herdadas para remoção.

O exemplo a seguir mostra um arquivo de manifesto com a versão definida como 2:

{
     "arn": "arn:aws:omics:us-west-2:12345678901:runCache/0123456/cacheEntry/1234567-195f-3921-a1fa-ffffcef0a6a4",
     "s3uri": "s3://example/1234567-d0d1-e230-d599-10f1539f4a32/1348677/4795326/7e8c69b1-145f-3991-a1fa-ffffcef0a6a4",
     "taskArn": "arn:aws:omics:us-west-2:12345678901:task/4567891",
     "workDir": "/mnt/workflow/1234567-d0d1-e230-d599-10f1539f4a32/workdir/call-TxtFileCopyTask/5w6tn5feyga7noasjuecdeoqpkltrfo3/wxz2fuddlo6hc4uh5s2lreaayczduxdm",
     "files": [
         {
             "name": "output_txt_file",
             "path": "out/output_txt_file/outfile.txt",
             "etag": "ajdhyg9736b9654673b9fbb486753bc8"
         }
     ],
     "nextflowContext": {},
     "otherOutputs": {},
     "version": 2,       
  }     

Para execuções com entradas de cache que não são mais válidas, reconstrua o cache para criar novas entradas válidas. Execute as seguintes etapas para cada execução:

1. Inicie a execução uma vez com a retenção de cache definida como CACHE ALWAYS. Essa execução cria as novas entradas de cache.

2. Para execuções subsequentes, defina a retenção do cache para a configuração anterior (CACHE ALWAYS ou CACHE ON FAILURE).

Para limpar as entradas de cache que não são mais válidas, você pode excluir essas entradas de cache do bucket cache do Amazon S3. HealthOmics nunca reutiliza essas entradas de cache. Se você optar por reter entradas que não são válidas, não haverá impacto em suas corridas.

nota

O cache de chamadas salva os dados de saída da tarefa no local do Amazon S3 especificado para o cache, o que gera cobranças para você. Conta da AWS

Comportamento do cache de execução

Você pode definir o comportamento do cache de execução para salvar as saídas da tarefa para execuções que falham (cache em caso de falha) ou para todas as execuções (cache sempre). Ao criar um cache de execução, você define o comportamento padrão do cache para todas as execuções que usam esse cache. Você pode substituir o comportamento padrão ao iniciar uma execução.

Cache on failureé útil se você estiver depurando um fluxo de trabalho que falha após a conclusão bem-sucedida de várias tarefas. A execução subsequente é retomada a partir da última tarefa concluída com êxito se todas as variáveis exclusivas consideradas pelo hash forem idênticas à execução anterior.

Cache alwaysé útil se você estiver atualizando uma tarefa em um fluxo de trabalho concluído com êxito. Recomendamos que você siga estas etapas:

1. Crie uma nova corrida. Defina o comportamento do Cache como Cache sempre e inicie a execução.

2. Depois que a execução for concluída, atualize a tarefa no fluxo de trabalho e inicie uma nova execução com o comportamento definido Cache always. Essa execução processa a tarefa atualizada e todas as tarefas subsequentes que dependam da tarefa atualizada. Todas as outras tarefas usam os resultados em cache.

3. Repita a etapa 2 conforme necessário, até que o desenvolvimento da tarefa atualizada esteja concluído.

4. Use a tarefa atualizada conforme necessário em execuções futuras. Lembre-se de alternar as execuções subsequentes para Cache em caso de falha se você planeja usar entradas novas ou diferentes para essas execuções.

nota

Recomendamos o modo Cache sempre usando o mesmo conjunto de dados de teste, mas não para um lote de execuções. Se você definir esse modo para um grande lote de execuções, o sistema poderá exportar grandes quantidades de dados para o Amazon S3, resultando em maiores tempos de exportação e custos de armazenamento.

Controle o tamanho do cache de execução

HealthOmics não exclui nem arquiva automaticamente nenhum dado de cache executado nem aplica as regras de limpeza do Amazon S3 para gerenciar os dados do cache. Recomendamos que você realize limpezas regulares do cache para economizar nos custos de armazenamento do Amazon S3 e manter o tamanho do cache de execução gerenciável. Você pode excluir arquivos diretamente ou definir retention/replication políticas de dados no bucket de execução do cache.

Por exemplo, você pode configurar uma política de ciclo de vida do Amazon S3 para expirar objetos após 90 dias ou pode limpar manualmente os dados do cache no final de cada projeto de desenvolvimento.

As informações a seguir podem ajudá-lo a gerenciar o tamanho dos dados do cache:

• Você pode ver quantos dados estão no cache verificando o Amazon S3. HealthOmics não monitora nem relata o tamanho do cache.

• Se você excluir uma entrada de cache válida, a execução subsequente não falhará. HealthOmics recalcula a tarefa e suas tarefas dependentes.

• Se você modificar nomes de cache ou estruturas de diretórios de forma que HealthOmics não consiga encontrar uma entrada correspondente para uma tarefa, HealthOmics recalculará a tarefa.

Se você precisar verificar se uma entrada de cache ainda é válida, verifique o número da versão do manifesto do cache. Para obter mais informações, consulte Atualizações de versões do manifesto e atualização de dados.