Resolver problemas de modelos flexíveis

Esta página fornece dicas de solução de problemas e estratégias de depuração que podem ser úteis se você estiver usando os modelos Flex do Dataflow. Por padrão, o processo de inicialização do modelo Flex tem um tempo limite de 12 minutos. Esse processo de inicialização inclui extrair a imagem do contêiner de modelo e executar o código para construir o gráfico de job. Se o lançamento não for concluído nesse período de 12 minutos, o job vai falhar com o erro "Timeout in polling result file". Essas informações podem ajudar a detectar um tempo limite de pesquisa, determinar o motivo do tempo limite e corrigir o problema.

Erros de tempo limite de pesquisa

O job pode retornar uma das seguintes mensagens de erro:

Timeout in polling result file: FILE_PATH. Possible causes are:
1. Your launch takes too long time to finish. Please check the logs on stackdriver.
2. Service account SERVICE_ACCOUNT may not have enough permissions to pull
container image IMAGE_PATH or create new objects in FILE_PATH.
3. Transient errors occurred, please try again.

Timeout in polling result file: FILE_PATH.
Service account: SERVICE_ACCOUNT
Image URL: IMAGE_PATH
Troubleshooting guide at https://cloud.google.com/dataflow/docs/guides/common-errors#timeout-polling

Esse problema pode ocorrer pelos seguintes motivos:

  1. A imagem Docker base foi substituída.
  2. A conta de serviço que preenche SERVICE_ACCOUNT não tem algumas permissões necessárias.
  3. Os endereços IP externos estão desativados, e as VMs não podem se conectar ao conjunto de endereços IP externos usados pelas APIs e serviços do Google.
  4. A VM de inicialização não consegue resolver ou acessar gcr.io.
  5. Imagem de contêiner do modelo Flex grande.
  6. O programa que cria o gráfico leva muito tempo para ser concluído.
  7. O código em execução na VM de inicialização demora muito para ser concluído.
  8. Erros intermitentes de rede ou do Cloud Storage.
  9. As opções de pipeline estão sendo substituídas.
  10. Usuários do Python: a instalação ou o preparo de dependências leva muito tempo.
  11. Ocorreu um erro temporário.

Para resolver esse problema, primeiro verifique se há erros temporários nos registros do job e tente novamente.

Siga as orientações na seção Problemas de inicialização antecipada para ativar a geração de registros da porta serial, que pode revelar mais informações.

Se isso não resolver o problema, tente as etapas a seguir.

Opcional: execute modelos para diagnosticar melhor o problema

Para identificar qual dos motivos anteriores pode estar causando esse erro, use as seguintes estratégias:

  1. Execute o modelo WordCount fornecido pelo Google. Forneça parâmetros exclusivos para seu caso de uso, como a sub-rede de um projeto de VPC compartilhada, o IP particular para VMs de worker e a conta de serviço do worker do Dataflow que você quer usar. Para mais informações sobre como fornecer esses parâmetros, consulte a Referência do gcloud e a Referência da API.

    Se você conseguir concluir esse job, isso indica que as permissões de rede e do IAM e o Acesso privado do Google provavelmente estão configurados corretamente.

  2. Conclua o guia de início rápido Executar um pipeline usando o criador de jobs, que executa o job como um modelo flexível. Se o job falhar antes de iniciar a VM de worker, acesse a VM de inicialização e tente fazer o download de uma imagem Docker de amostra usando um comando semelhante a este:

    docker run --entrypoint /bin/bash -it gcr.io/dataflow-templates/2025-03-11-00_rc02/yaml-template

    Se esse comando falhar, talvez haja um problema de rede com o download de imagens. Nesse caso, trabalhe com sua equipe interna de rede.

  3. Execute um modelo flexível fornecido pelo Google e verifique o resultado. Se o job de modelo fornecido pelo Google for concluído com sucesso, isso indica que o problema provavelmente está relacionado aos seus arquivos de código de modelo personalizado específicos. Nesse caso, continue resolvendo problemas no seu código específico para resolver o problema.

Verificar o ponto de entrada do Docker

Siga esta etapa se você estiver executando um modelo de uma imagem Docker personalizada em vez de usar um dos modelos fornecidos.

Verifique o ponto de entrada do contêiner usando o comando a seguir:

docker inspect $TEMPLATE_IMAGE

A saída a seguir é esperada:

Java

/opt/google/dataflow/java_template_launcher

Python

/opt/google/dataflow/python_template_launcher

Se você receber uma saída diferente, o ponto de entrada do contêiner do Docker será modificado. Restaure $TEMPLATE_IMAGE para o padrão.

Verificar as permissões da conta de serviço

Verifique se a conta de serviço mencionada na mensagem tem as seguintes permissões:

  • Ele precisa ler e gravar o caminho do Cloud Storage que preenche o ${file_path} na mensagem.
  • Ele precisa ler a imagem Docker que preenche ${image_url} na mensagem.

Configurar Acesso privado do Google

Se os endereços IP externos estiverem desativados, você precisará permitir que as VMs do Compute Engine se conectem ao conjunto de endereços IP externos usado pelas APIs e serviços do Google. Ative o Acesso privado do Google na sub-rede usada pela interface de rede da VM.

Para detalhes sobre a configuração, consulte Como configurar o Acesso privado do Google.

Por padrão, quando uma VM do Compute Engine não tem um endereço IP externo atribuído à interface de rede dela, ela só pode enviar pacotes para outros destinos de endereço IP interno.

Problemas de acesso ao GCR.io

As VMs do inicializador de modelos flexíveis precisam de acesso ao gcr.io para extrair um contêiner do agente de geração de registros (gcr.io/dataflow-templates-base/template-launcher-logger-distroless). Esse agente é responsável por transmitir os registros do inicializador para o Cloud Logging. Se a VM de inicialização não conseguir resolver ou se conectar a gcr.io, o processo de inicialização poderá parar de responder, resultando em um tempo limite de polling.

Esse problema pode ocorrer mesmo que a imagem do modelo personalizado esteja armazenada no Artifact Registry, porque o agente de geração de registros é sempre extraído de gcr.io.

Para diagnosticar e resolver esse problema:

  1. Ative a geração de registros da porta serial: siga as etapas na seção Problemas de inicialização antecipada. Se o processo cloud-init estiver travado ou se houver erros relacionados a gcr-wait-online.service, provavelmente há um problema de DNS ou de rede.

  2. Conecte-se à VM de inicialização por SSH: use o comando gcloud compute ssh para se conectar à VM de inicialização enquanto ela ainda está em execução:

    gcloud compute ssh launcher-JOB_ID --tunnel-through-iap

    Substitua JOB_ID pelo ID do seu job do Dataflow.

  3. Verifique a resolução de DNS: execute os seguintes comandos na VM de inicialização:

    curl -I https://gcr.io

    Se o comando falhar com um erro "Could not resolve host", sua configuração de DNS não tem uma entrada para gcr.io.

  4. Verifique se há serviços de inicialização presos: examine o registro de saída cloud-init:

    sudo cat /var/log/cloud-init-output.log

    Procure mensagens indicando que o processo está aguardando a rede ou que gcr.io seja acessível.

Além disso, verifique se as configurações de DNS da VPC permitem a resolução de gcr.io. Em algumas configurações de rede privada, talvez seja necessário adicionar um registro DNS A específico para gcr.io apontando para os intervalos de IP das APIs restritas ou particulares do Google.

Imagem de contêiner grande

Se a imagem do contêiner do modelo Flex for grande, a extração e o lançamento do modelo poderão exceder o tempo limite padrão de 12 minutos, causando falha no job.

Para minimizar o problema, tente as seguintes estratégias :

  • Otimize a imagem para reduzir o tamanho dela e acelerar o processo de extração.
  • Use a flag --launcher-machine-type para selecionar um tipo de máquina com mais núcleos de CPU, o que ajuda a extrair a imagem mais rápido e leva a uma inicialização mais rápida.
  • Use a flag --launcher-vm-timeout-secs para especificar um tempo limite maior para a VM de inicialização, permitindo que ela ultrapasse o limite padrão de 12 minutos.

Verificar se o programa tela de início falha ao sair

O programa que constrói o pipeline precisa terminar antes que ele possa ser iniciado. O erro de pesquisa pode indicar que demorou muito para isso.

Algumas coisas que você pode fazer para localizar a causa no código são:

  • Verifique se nenhuma linha de execução está bloqueando a saída do programa. Alguns clientes podem criar as próprias linhas de execução e, se esses clientes não forem desligados, o programa aguardará para sempre que essas linhas sejam mescladas.
  • No código que define seu pipeline, não use waitUntilFinish (para Java) ou wait_until_finish (para Python). Essas funções impedem que o programa se encerre, o que impede que o modelo flexível inicie o pipeline.

Os pipelines iniciados diretamente que não usam um modelo não têm essas limitações. Portanto, se o canal funcionou diretamente, mas não como um modelo, o uso de um modelo pode ser a causa raiz. Encontrar o problema no modelo e corrigi-lo pode resolvê-lo.

Código de longa duração na VM de inicialização

Se o código no programa principal demorar muito para ser executado, o modelo Flex poderá atingir o tempo limite antes do lançamento do pipeline. Isso pode acontecer se o código realizar cálculos complexos ou fizer chamadas síncronas para recursos externos durante a inicialização.

Para diagnosticar esse problema, verifique os registros do job e procure operações que demoram muito para ser concluídas. Exemplos incluem solicitações de recursos externos, grandes pesquisas de dados ou lógica de inicialização pesada que pode ser movida para a fase de execução do pipeline.

Erros intermitentes de rede ou do Cloud Storage

Erros intermitentes de "Tempo limite no arquivo de resultado da sondagem" ou "Não foi possível ler o arquivo de resultado" podem ocorrer devido à alta latência da rede ou a problemas transitórios com a API Storage do Cloud Storage. A disputa de rede crônica na sua VPC, especificamente no caminho do Acesso privado do Google, geralmente causa latências de 400 a 500 ms.

Um "Tempo limite no arquivo de resultado da pesquisa" geralmente é uma falha lenta, enquanto uma "Falha ao ler o arquivo de resultado" é uma falha rápida, mas ambas costumam indicar o mesmo problema de conectividade subjacente.

Para diagnosticar essas falhas intermitentes:

  1. Verificar a latência de rede: monitore a latência de rede na sua VPC. A alta latência sustentada pode causar tempos limite quando a VM de inicialização tenta gravar ou ler o arquivo de resultado do job no Cloud Storage.

  2. Monitore as métricas da API Storage:

    1. No console do Google Cloud , acesse o painel APIs e serviços.

      Acessar APIs e serviços ativados

    2. Filtre e selecione a API Storage Cloud.

    3. Analise os gráficos de Tráfego (bytes enviados e recebidos) e Taxa de erros.

    4. Procure picos nos erros 5xx (como erros 503) que se alinham com o horário exato das falhas do job.

Se você identificar picos de erros ou alta latência, investigue o desempenho da rede da sua VPC ou entre em contato com o atendimento ao cliente do Cloud para receber ajuda com possíveis interrupções no serviço.

Verificar se as opções de pipeline necessárias foram suprimidas

Ao usar modelos Flex, é possível configurar algumas, mas não todas, as opções de pipeline durante a inicialização. Para mais informações, consulte a seção Falha ao ler o arquivo de job neste documento.

Usuários do Python: gerenciamento de dependências

Se você estiver executando um job de modelo flexível do Python que fornece dependências extras em um arquivo requirements.txt, o job poderá falhar ao ser iniciado. Essa falha ocorre quando o download ou a instalação das dependências especificadas no arquivo de requisitos leva mais tempo do que o alocado para iniciar o modelo Flex.

Para otimizar o desempenho do job, pré-empacote as dependências ao criar o modelo para evitar o download ou a instalação das dependências durante a inicialização do modelo. Para mais informações, consulte a seção Dependências de pacote para Python em "Configurar modelos flexíveis".

Falhas na inicialização do job

A seção a seguir contém erros comuns que levam a falhas na inicialização do job e etapas para resolver ou solucionar os problemas.

Problemas iniciais de inicialização

Quando o processo de inicialização do modelo falha em um estágio inicial, os registros regulares de modelo Flex podem não estar disponíveis. Para investigar problemas de inicialização, ative a geração de registros de porta serial para a VM da tela de início de modelos.

Para ativar a geração de registros para modelos Java, defina a opção enableLauncherVmSerialPortLogging como true. Para ativar a geração de registros para modelos Python e Go, defina a opção enable_launcher_vm_serial_port_logging como true. No console Google Cloud , o parâmetro é listado em Parâmetros opcionais como Ativar registro de portas seriais da VM de acesso rápido.

É possível visualizar os registros de saída da porta serial da VM do iniciador de modelos no Cloud Logging. Para encontrar os registros de uma determinada VM da tela de início, use a consulta resource.type="gce_instance" "launcher-number", em que number começa com a data atual no formato YYYMMDD.

A política da organização pode proibir a ativação da geração de registros de saída da porta serial.

Falha ao ler o arquivo do job

Quando você tenta executar um job com base em um modelo Flex, o job pode falhar e apresentar o seguinte erro:

Failed to read the job file : gs://dataflow-staging-REGION-PROJECT_ID/staging/template_launches/TIMESTAMP/job_object...

Esse erro ocorre quando as opções de inicialização do pipeline necessárias são substituídas. Ao usar modelos Flex, é possível configurar algumas, mas não todas, as opções de pipeline durante a inicialização dele. Se os argumentos de linha de comando exigidos pelo modelo Flex forem substituídos, o job pode ignorar, substituir ou descartar as opções de pipeline transmitidas pelo inicializador de modelos. A inicialização do job pode falhar ou um job que não usa o modelo Flex pode ser iniciado.

Para evitar esse problema, durante a inicialização do pipeline, não altere as seguintes opções de pipeline no código do usuário ou no arquivo metadata.json:

Java

  • runner
  • project
  • jobName
  • templateLocation
  • region

Python

  • runner
  • project
  • job_name
  • template_location
  • region

Go

  • runner
  • project
  • job_name
  • template_location
  • region

Não foi possível ler o arquivo de resultados

Quando você tenta executar um job com base em um modelo Flex, o job pode falhar e apresentar o seguinte erro:

Failed to read the result file : gs://BUCKET_NAME...

Esse erro ocorre quando a conta de serviço padrão do Compute Engine não tem todas as permissões necessárias para executar um modelo Flex.

Para conferir a lista de permissões necessárias, consulte Permissões para executar um modelo flexível.

Esse erro também pode ser causado por latência intermitente da rede ou problemas na API Cloud Storage. Para mais informações, consulte Erros intermitentes de rede ou do Cloud Storage.

Permissão negada no recurso

Quando você tenta executar um job com base em um modelo Flex, o job pode falhar e apresentar o seguinte erro:

Permission "MISSING_PERMISSION" denied on resource "projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME" (or it may not exist).

Esse erro ocorre quando a conta de serviço usada não tem permissões para acessar os recursos necessários para executar um modelo Flex.

Para evitar esse problema, verifique se a conta de serviço tem as permissões necessárias. Ajuste as permissões da conta de serviço conforme necessário.

Flag fornecida, mas não definida

Quando você tenta executar um modelo Go Flex com a opção de pipeline worker_machine_type, o pipeline falha com o seguinte erro:

flag provided but not defined: -machine_type

Esse erro é causado por um problema conhecido nas versões 2.47.0 e anteriores do SDK do Apache Beam para Go. Para resolver esse problema, faça upgrade para o Apache Beam Go versão 2.48.0 ou mais recente.

Não foi possível buscar o jar do servidor de jobs remoto

Se você tentar executar um job usando um modelo Flex quando não estiver conectado à Internet, o job poderá falhar e apresentar o seguinte erro:

Unable to fetch remote job server jar at
https://repo.maven.apache.org/maven2/org/apache/beam/beam-sdks-java-io-expansion-service/VERSION/beam-sdks-java-io-expansion-service-VERSION.jar:
\u003curlopen error [Errno 101] Network is unreachable\u003e

Esse erro ocorre porque a VM não consegue fazer o download do pacote Java do Apache Beam da Internet. Esse pacote é necessário quando você executa um job em vários idiomas usando um modelo Flex.

Para resolver esse problema, faça uma das alterações a seguir:

  • Conecte-se à Internet. Quando conectado à Internet, o job pode acessar o arquivo necessário.

  • Inclua o pacote Java do Apache Beam no diretório local para que o job possa acessá-lo. Coloque o arquivo no seguinte diretório: /root/.apache_beam/cache/jars/. Por exemplo, /root/.apache_beam/cache/jars/beam-sdks-java-io-expansion-service-SDK_VERSION.jar.

Não foi possível acessar o sistema de arquivos do caminho especificado

Quando você tenta executar um job com base em um modelo Flex, o job pode falhar e apresentar o seguinte erro:

ValueError: Unable to get filesystem from specified path, please use
the correct path or ensure the required dependency is installed, e.g., pip
install apache-beam[gcp]. Path specified: PATH

Esse erro ocorre quando o job usa uma imagem de contêiner do modelo flexível e a imagem do contêiner não contém uma instalação do Java.

Para resolver esse problema, adicione a seguinte linha ao Dockerfile:

sh RUN apt-get update && apt-get install -y openjdk-17-jdk

Esse comando instala o Java no ambiente do contêiner.

Esgotamento de recursos da VM de inicialização

Quando você tenta executar um job com base em um modelo Flex, ele pode falhar e apresentar o seguinte erro:

Failed to start the VM, launcher-ID, used for launching because of status code: INTERNAL, reason: Unknown error in operation 'OPERATION_ID': [ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS] 'The zone 'projects/PROJECT_ID/zones/ZONE_ID' does not have enough resources available to fulfill the request.

O nome da VM launcher-ID representa o nome da VM de inicialização. A VM de inicialização é responsável por reunir recursos do job, como o código e a imagem do modelo, antes de criar e enviar o gráfico do job ao serviço do Dataflow para iniciar o trabalho.

Se você não especificar o parâmetro launcherMachineType, o Dataflow vai escolher um tipo de máquina padrão para a VM de inicialização. Essa escolha é independente do worker machineType. Erros de falta de recursos podem ocorrer se esse tipo de máquina padrão não estiver disponível na região ou zona do job.

Para resolver esse problema, use uma das seguintes estratégias:

Atraso na tela de início do modelo Flex

Quando você envia um job de modelo flexível, a solicitação de job entra em uma fila do Spanner. A tela de início do modelo pega o job da fila do Spanner e, em seguida, executa o modelo. Quando o Spanner tem um backlog de mensagens, pode ocorrer um atraso significativo entre o momento em que você envia o job e o momento em que ele é iniciado.

Para contornar esse problema, inicie seu modelo Flex em uma região diferente.

Os parâmetros do modelo são inválidos

Ao tentar usar a CLI gcloud para executar um job que usa um modelo fornecido pelo Google, ocorre o seguinte erro:

ERROR: (gcloud.beta.dataflow.flex-template.run) INVALID_ARGUMENT: The template
parameters are invalid. Details: defaultSdkHarnessLogLevel: Unrecognized
parameter defaultWorkerLogLevel: Unrecognized parameter

Esse erro ocorre porque alguns modelos fornecidos pelo Google não são compatíveis com as opções defaultSdkHarnessLog e defaultWorkerLog.

Para resolver esse problema, use o método adequado ao tipo de modelo.

Modelos Flex

Para modelos flexíveis, use a flag --additional-pipeline-options para transmitir as opções de pipeline como uma string. Por exemplo, usando o comando gcloud dataflow flex-template run:

gcloud dataflow flex-template run JOB_NAME \
--template-file-gcs-location=GCS_TEMPLATE_PATH \
--additional-pipeline-options=defaultSdkHarnessLogLevel=WARN,defaultWorkerLogLevel=WARN

Substitua os seguintes valores:

  • JOB_NAME: o nome do job do Dataflow
  • GCS_TEMPLATE_PATH: o caminho do Cloud Storage para o arquivo de modelo.
Modelos clássicos

Para modelos clássicos, a solução alternativa é copiar o arquivo de especificação do modelo para um bucket do Cloud Storage e adicionar os seguintes parâmetros ao arquivo.

"metadata": {
    ...
    "parameters": [
      ...,
      {
        "name": "defaultSdkHarnessLogLevel",
        "isOptional": true,
        "paramType": "TEXT"
      },
      {
        "name": "defaultWorkerLogLevel",
        "isOptional": true,
        "paramType": "TEXT"
      }
    ]
  }

Depois de fazer essa mudança no arquivo de modelo, use a seguinte flag ao executar o modelo.

--gcs-location=gs://BUCKET_NAME/FILENAME

Substitua os seguintes valores:

  • BUCKET_NAME: o nome do bucket do Cloud Storage
  • FILENAME: o nome do arquivo de especificação do modelo

Os registros do inicializador do modelo Flex mostram gravidade incorreta

Quando uma inicialização de modelo Flex personalizado falha, a seguinte mensagem aparece nos arquivos de registro com a gravidade ERROR:

ERROR: Error occurred in the launcher container: Template launch failed. See console logs.

A causa raiz da falha de inicialização geralmente aparece nos registros anteriores a essa mensagem com a gravidade INFO. Esse nível de registro pode estar incorreto, mas isso é esperado, já que o inicializador do modelo Flex não tem como extrair detalhes de gravidade das mensagens de registro produzidas pelo aplicativo Apache Beam.

Se você quiser ver a gravidade correta para cada mensagem no registro do inicializador, configure seu modelo para que gere registros no formato JSON no lugar de texto simples. Essa configuração permite que o inicializador do modelo extraia a gravidade correta da mensagem de registro. Use a seguinte estrutura de mensagem:

{
  "message": "The original log message",
  "severity": "DEBUG/INFO/WARN/ERROR"
}

Em Java, é possível usar o registrador Logback com uma implementação personalizada do anexador JSON. Para mais informações, consulte o exemplo de configuração do Logback e o exemplo de código do anexador JSON (em inglês) no GitHub.

Esse problema só afeta os registros gerados pelo inicializador do modelo Flex quando o pipeline está sendo iniciado. Quando a inicialização é bem-sucedida e o pipeline está em execução, os registros produzidos pelos workers do Dataflow têm a gravidade adequada.

Os modelos fornecidos pelo Google mostram a gravidade correta durante a inicialização do job, porque eles usam essa abordagem de geração de registros JSON.