Usar amostragem de dados para observar dados do pipeline

Com a amostragem de dados, é possível observar os dados em cada etapa de um pipeline do Dataflow. Essas informações podem ajudar você a depurar problemas com o pipeline, mostrando as entradas e saídas reais em um job em execução ou concluído.

A amostragem de dados inclui os seguintes usos:

  • Durante o desenvolvimento, veja quais elementos são produzidos em todo o pipeline.

  • Se um pipeline gerar uma exceção, visualize os elementos que estão correlacionados a essa exceção.

  • Ao depurar, visualize as saídas das transformações para garantir que elas estejam corretas.

  • Entenda o comportamento de um pipeline sem precisar examinar seu código.

  • Visualize mais tarde os elementos de amostra, após a conclusão do job, ou compare os dados de amostra com uma execução anterior.

Visão geral

O Dataflow pode criar amostras de dados de pipeline das seguintes maneiras:

  • Amostragem periódica. Com esse tipo de amostragem, o Dataflow coleta amostras à medida que o job é executado. É possível usar os dados de amostra para verificar se o pipeline processa elementos conforme esperado e para diagnosticar problemas no ambiente de execução, como teclas de atalho ou saídas incorretas. Para mais informações, consulte a seção Usar amostragem de dados periódica neste documento.

  • Amostragem de exceções: Com esse tipo de amostragem, o Dataflow coleta amostras se um pipeline gerar uma exceção. Você pode usar as amostras para ver os dados que estavam sendo processados quando a exceção ocorreu. A amostragem de exceções é ativada por padrão e pode ser desativada. Para mais informações, consulte Usar amostragem de exceções neste documento.

O Dataflow grava os elementos de amostra no caminho do Cloud Storage especificado pela opção de pipeline temp_location. É possível visualizar os dados de amostra no console do Google Cloud ou examinar os arquivos de dados brutos no Cloud Storage. Os arquivos serão mantidos no Cloud Storage até você os excluir.

A amostragem de dados é executada pelos workers do Dataflow. A amostragem é baseada no Best-Effort. As amostras poderão ser descartadas se ocorrerem erros temporários.

Requisitos

Para usar a amostragem de dados, ative o Runner v2. Para mais informações, consulte Ativar o Dataflow Runner v2.

Para ver os dados de amostra no console do Google Cloud, você precisa das seguintes permissões do Identity and Access Management:

  • storage.buckets.get
  • storage.objects.get
  • storage.objects.list

A amostragem periódica requer os seguintes SDK do Apache Beam:

  • SDK do Apache Beam para Java 2.47.0 ou posterior
  • SDK do Apache Beam para Python 2.46.0 ou posterior
  • SDK do Apache Beam para Go 2.53.0 ou mais recente

A amostragem de exceções requer o seguinte SDK do Apache Beam:

  • SDK do Apache Beam para Java 2.51.0 ou mais recente
  • SDK do Apache Beam para Python 2.51.0 ou mais recente
  • O SDK do Apache Beam para Go não oferece suporte à amostragem de exceções.

Começando com esses SDKs, o Dataflow permite a amostragem de exceções para todos os jobs por padrão.

Usar amostragem de dados periódica

Nesta seção, descrevemos como criar amostras de dados de pipeline continuamente durante a execução de um job.

Ativar a amostragem de dados periódica

A amostragem periódica está desativada por padrão. Para ativá-la, defina a seguinte opção de pipeline:

Java

--experiments=enable_data_sampling

Python

--experiments=enable_data_sampling

Go

--experiments=enable_data_sampling

É possível definir a opção de maneira programática ou usando a linha de comando. Para mais informações, consulte Definir opções de pipeline do Dataflow.

Ao executar um modelo do Dataflow, use a sinalização additional-experiments para ativar a amostragem de dados:

--additional-experiments=enable_data_sampling

Quando a amostragem periódica está ativada, o Dataflow coleta amostras de cada PCollection no gráfico do job. A taxa de amostragem é de aproximadamente uma amostra a cada 30 segundos.

Dependendo do volume de dados, a amostragem de dados periódica pode adicionar um overhead significativo de desempenho. Portanto, recomendamos que você ative a amostragem periódica somente durante o teste e desative-a para cargas de trabalho de produção.

Conferir dados de amostra

Para visualizar os dados de amostra no console do Google Cloud, execute as seguintes etapas:

  1. No console do Google Cloud, acesse a página Jobs do Dataflow.

    Acessar "Jobs"

  2. Selecione um job.

  3. Clique em no painel inferior para expandir o painel de registros.

  4. Clique na guia Amostragem de dados.

  5. No campo Etapa, selecione uma etapa do pipeline. Também é possível selecionar uma etapa no gráfico do job.

  6. No campo Coleção, escolha uma PCollection.

Se o Dataflow tiver coletado amostras para essa PCollection, os dados de amostra serão exibidos na guia. Para cada amostra, a guia exibe a data de criação e o elemento de saída. O elemento de saída é uma representação serializada do elemento de coleção, incluindo os dados do elemento, o carimbo de data/hora e as informações da janela e do painel.

Os exemplos a seguir mostram elementos de amostra.

Java

TimestampedValueInGlobalWindow{value=KV{way, [21]},
timestamp=294247-01-09T04:00:54.775Z, pane=PaneInfo{isFirst=true, isLast=true,
timing=ON_TIME, index=0, onTimeIndex=0}}

Python

(('THE', 1), MIN_TIMESTAMP, (GloblWindow,), PaneInfo(first: True, last: True,
timing: UNKNOWN, index: 0, nonspeculative_index: 0))

Go

KV<THE,1> [@1708122738999:[[*]]:{3 true true 0 0}]

A imagem a seguir mostra como os dados de amostra são exibidos no console do Google Cloud.

Dados de amostra no console do Google Cloud

Usar amostragem de exceções

Se o pipeline gerar uma exceção não processada, será possível visualizar a exceção e o elemento de entrada correlacionado a essa exceção. A amostragem de exceções é ativada por padrão quando você usa um SDK do Apache Beam compatível.

Visualizar exceções

Para ver uma exceção, siga estas etapas:

  1. No console do Google Cloud, acesse a página Jobs do Dataflow.

    Acessar "Jobs"

  2. Selecione um job.

  3. Para expandir o painel Registros, clique em Alternar painel no painel Registros.

  4. Clique na guia Amostragem de dados.

  5. No campo Etapa, selecione uma etapa do pipeline. Também é possível selecionar uma etapa no gráfico do job.

  6. No campo Coleção, escolha uma PCollection.

    A coluna Exceção contém os detalhes da exceção. Não há elemento de saída para uma exceção. Em vez disso, a coluna Elemento de saída contém a mensagem Failed to process input element: INPUT_ELEMENT, em que INPUT_ELEMENT é o elemento de entrada correlacionado.

  7. Para conferir a amostra de entrada e os detalhes da exceção em uma nova janela, clique em Abrir em uma nova.

A imagem a seguir mostra como uma exceção aparece no console do Google Cloud.

Exceção com amostragem no console do Google Cloud

Desativar a amostragem de exceções

Para desativar a amostragem de exceções, defina a seguinte opção de pipeline:

Java

--experiments=disable_always_on_exception_sampling

Python

--experiments=disable_always_on_exception_sampling

É possível definir a opção de maneira programática ou usando a linha de comando. Para mais informações, consulte Definir opções de pipeline do Dataflow.

Ao executar um modelo do Dataflow, use a flag additional-experiments para desativar a amostragem de exceções:

--additional-experiments=disable_always_on_exception_sampling

Considerações sobre segurança

O Dataflow grava os dados da amostra em um bucket do Cloud Storage criado e gerenciado por você. Use os recursos de segurança do Cloud Storage para proteger seus dados. Em especial, considere estas outras medidas de segurança:

  • Use uma chave de criptografia gerenciada pelo cliente (CMEK, na sigla em inglês) para criptografar o bucket do Cloud Storage. Para mais informações sobre como escolher a opção de criptografia certa para suas necessidades, consulte este link.
  • Defina um time to live (TTL) no bucket do Cloud Storage para que os arquivos de dados sejam excluídos automaticamente após um período. Para mais informações, consulte Definir a configuração do ciclo de vida de um bucket.
  • Use o princípio de privilégio mínimo quando for atribuir permissões do IAM ao bucket do Cloud Storage.

Também é possível ofuscar campos individuais no tipo de dados PCollection para que o valor bruto não apareça nos dados de amostra:

  • Python: substitua o método __repr__ ou __str__.
  • Java: substitua o método toString.

No entanto, não é possível ofuscar as entradas e saídas dos conectores de E/S, a menos que você modifique o código-fonte do conector para fazer isso.

Faturamento

Quando o Dataflow realiza a amostragem de dados, você é cobrado pelo armazenamento de dados do Cloud Storage e pelas operações de leitura e gravação no Cloud Storage. Para mais informações, consulte Preços do Cloud Storage.

Cada worker do Dataflow grava amostras em lotes, gerando uma operação de leitura e uma operação de gravação por lote.

Solução de problemas

Esta seção contém informações sobre problemas comuns ao usar a amostragem de dados.

Erro de permissões

Se você não tiver permissão para visualizar as amostras, o console do Google Cloud mostrará o seguinte erro:

You don't have permission to view a data sample.

Para resolver esse erro, verifique se você tem as permissões necessárias do IAM. Se o erro persistir, talvez uma política de negação do IAM esteja sendo aplicada a você.

Não vejo amostras

Se você não vir amostras, faça estas verificações:

  1. Configure a opção enable_data_sampling para garantir que a amostragem de dados esteja ativada. Consulte Ativar amostragem de dados.
  2. Verifique se você está usando o Runner v2.
  3. Verifique se os workers foram iniciados. A amostragem não começa até que os workers sejam iniciados.
  4. Verifique se o job e os workers estão íntegros.
  5. Verifique as cotas do Cloud Storage do projeto. Se você exceder os limites de cota do Cloud Storage, o Dataflow não gravará os dados de amostra.
  6. A amostragem de dados não pode gerar amostras de iteráveis. As amostras desses tipos de streams não estão disponíveis.

A seguir