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. 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 externo usados pelas APIs e serviços do Google.
4. A VM do inicializador não consegue resolver ou acessar gcr.io.
5. O programa que cria o gráfico leva muito tempo para ser concluído.
6. O código em execução na VM do inicializador leva muito tempo para ser concluído.
7. Erros intermitentes de rede ou do Cloud Storage.
8. As opções de pipeline estão sendo substituídas.
9. Usuários do Python: a instalação ou o preparo de dependências leva muito tempo.
10. 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 iniciais de inicialização para ativar a geração de registros de porta serial, que pode revelar mais informações.

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

Opcional: executar modelos para diagnosticar melhor o problema

Para identificar melhor 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 da gcloud e a Referência da API.

   Se você conseguir concluir esse job, isso indica que as permissões de rede, do IAM e do Acesso privado do Google provavelmente estão configuradas 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 do inicializador 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, pode haver um problema de rede com o download de imagens. Nesse caso, trabalhe com sua equipe de rede interna.

3. Execute um modelo flexível fornecido pelo Google e verifique o resultado. Se o job do modelo fornecido pelo Google for concluído, isso indica que o problema provavelmente está relacionado aos arquivos de código do modelo personalizado. Nesse caso, continue a solução de problemas do 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 do 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 exigem 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 registros do inicializador para o Cloud Logging. Se a VM do inicializador não puder resolver ou se conectar ao gcr.io, o processo de inicialização poderá parar de responder, levando a um tempo limite de pesquisa.

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 do gcr.io.

Para diagnosticar e resolver esse problema:

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

2. Faça login na VM do inicializador usando SSH: use o comando gcloud compute ssh para se conectar à VM do inicializador enquanto ela ainda estiver 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 comandos a seguir na VM do inicializador:

   curl -I https://gcr.io
   

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

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

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

   Procure mensagens que indiquem que o processo está aguardando a rede ou o gcr.io ficar 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 particular, talvez seja necessário adicionar um registro A de DNS específico para gcr.io que aponte para os intervalos de IP das APIs restritas do Google ou das APIs particulares do Google.

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 de execução sejam unidas.
• No código que define o pipeline, não use waitUntilFinish (para Java) ou wait_until_finish (para Python). Essas funções impedem que o programa seja encerrado, 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 execução longa na VM do inicializador

Se o código no programa principal levar muito tempo para ser executado, o modelo flexível poderá atingir o tempo limite antes do início do pipeline. Isso pode acontecer se o código realizar cálculos complexos ou fazer chamadas síncronas para recursos externos durante a inicialização.

Para diagnosticar esse problema, verifique os registros do job para qualquer operação que leve muito tempo para ser concluída. Os exemplos incluem solicitações de recursos externos, pesquisas de dados grandes ou lógica de inicialização pesada que você pode mover 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 pesquisa" ou "Falha ao ler o arquivo de resultado" podem ocorrer devido à alta latência de rede ou a problemas temporários com a API Storage do Cloud Storage. A disputa de rede crônica na 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" é normalmente uma falha lenta, enquanto uma "Falha ao ler o arquivo de resultado" é uma falha rápida, mas ambas geralmente indicam o mesmo problema de conectividade subjacente.

Para diagnosticar essas falhas intermitentes:

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

2. Monitore as métricas da API Storage:

   1. No Google Cloud console do, 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 em erros 5xx (como erros 503) que se alinham ao horário exato das falhas do job.

Se você identificar picos de erros ou alta latência, investigue o desempenho da rede da VPC ou entre em contato com o atendimento ao cliente do Cloud para receber ajuda com possíveis interrupções de 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 a necessidade de fazer o download ou instalar as dependências durante a inicialização do modelo. Para mais informações, consulte a seção Empacotar dependências 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 Google Cloud console do, 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

Falha ao ler o arquivo de resultado

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ível.

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 de rede intermitente ou problemas da API Storage do Cloud Storage. Para mais informações, consulte Erros intermitentes de rede ou do Cloud Storage errors.

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 do inicializador

Quando você tenta executar um job com base em um modelo Flex, o job 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 do inicializador. A VM do inicializador é responsável por coletar recursos de job, como o código e a imagem do modelo, antes de criar e enviar o gráfico de 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 do inicializador. Essa escolha é independente do machineType do worker. Erros de esgotamento 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:

• Atualize o tipo de máquina do inicializador para um tipo diferente machine type e tente o job novamente.
  • API REST: defina launchParameter.environment.launcherMachineType no método flexTemplates.launch.
  • CLI gcloud: defina a --launcher-machine-type flag no comando gcloud dataflow flex-template run.
• Inicie seu modelo Flex em uma região diferente region.

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.

Como solução alternativa, copie o arquivo de especificação do modelo para um bucket do Cloud Storage. Adicione os seguintes parâmetros ao arquivo.

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

Depois de fazer essa alteração no arquivo de modelo, use o comando a seguir para executar o modelo.

--template-file-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.