Resolva problemas com os modelos flexíveis

Esta página fornece sugestões de resolução de problemas e estratégias de depuração que podem ser úteis se estiver a usar modelos flexíveis do Dataflow. Estas informações podem ajudar a detetar um limite de tempo de sondagem, determinar o motivo do limite de tempo e corrigir o problema.

Erros de limite de tempo de sondagem

O seu trabalho pode devolver 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

Este erro 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 autorizações necessárias.
  3. Os endereços IP externos estão desativados e as VMs não conseguem estabelecer ligação ao conjunto de endereços IP externos usados pelas APIs e pelos serviços Google.
  4. O programa que cria o gráfico demora demasiado tempo a terminar.
  5. As opções do pipeline estão a ser substituídas.
  6. Utilizadores do Python: a instalação ou a preparação de dependências demora demasiado tempo.
  7. Ocorreu um erro temporário.

Para resolver este problema, verifique primeiro se existem erros temporários consultando os registos de tarefas e tentando novamente.

Siga as orientações na secção Problemas de arranque antecipado para ativar o registo da porta série, o que pode revelar informações adicionais.

Se esses passos não resolverem o problema, experimente os seguintes passos de resolução de problemas.

Opcional: execute modelos para diagnosticar melhor o seu problema

Para identificar melhor qual dos motivos anteriores pode estar a causar este erro, use as seguintes estratégias:

  1. Execute o modelo fornecido pela Google WordCount. Certifique-se de que fornece parâmetros exclusivos para o seu exemplo de utilização, como a sub-rede de um projeto de VPC partilhada, o IP privado para VMs de trabalho e a conta de serviço do trabalhador do Dataflow que quer usar. Para mais informações sobre como fornecer estes parâmetros, consulte a referência gcloud e a referência API.

    Se conseguir concluir esta tarefa com êxito, significa que as autorizações de rede, IAM e acesso privado à Google estão provavelmente configuradas corretamente.

  2. Conclua o início rápido Execute um pipeline com o criador de tarefas, que executa a tarefa como um modelo flexível. Se a tarefa falhar antes de iniciar a VM do trabalhador, aceda à VM do iniciador e tente transferir uma imagem Docker de exemplo com um comando semelhante ao seguinte:

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

    Se este comando falhar, pode existir um problema de rede com a transferência de imagens. Neste caso, colabore com a sua equipa de rede interna.

  3. Execute um modelo flexível fornecido pela Google e verifique o resultado. Se a tarefa de modelo fornecida pela Google for concluída com êxito, isto indica que o problema está provavelmente relacionado com os seus ficheiros de código de modelo personalizado específicos. Neste caso, tem de continuar a resolver problemas do seu código específico para resolver o problema.

Valide o ponto de entrada do Docker

Experimente este passo se estiver a executar um modelo a partir de uma imagem do Docker personalizada em vez de usar um dos modelos fornecidos.

Verifique o ponto de entrada do contentor através do seguinte comando:

docker inspect $TEMPLATE_IMAGE

O seguinte resultado é esperado:

Java

/opt/google/dataflow/java_template_launcher

Python

/opt/google/dataflow/python_template_launcher

Se receber um resultado diferente, significa que o ponto de entrada do contentor Docker foi substituído. Restaurar $TEMPLATE_IMAGE para a predefinição.

Verifique as autorizações da conta de serviço

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

  • Tem de conseguir ler e escrever o caminho do Cloud Storage que preenche ${file_path} na mensagem.
  • Tem de conseguir ler a imagem de Docker que preenche ${image_url} na mensagem.

Configure o acesso privado do Google

Se os endereços IP externos estiverem desativados, tem de permitir que as VMs do Compute Engine se liguem ao conjunto de endereços IP externos usados pelas APIs e serviços Google. Ative o acesso privado à Google na sub-rede usada pela interface de rede da VM.

Para ver detalhes de configuração, consulte o artigo Configurar o acesso privado à Google.

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

Verifique se o programa do launcher não é terminado

O programa que cria o pipeline tem de terminar antes de o pipeline poder ser iniciado. O erro de sondagem pode indicar que demorou demasiado tempo a fazê-lo.

Seguem-se algumas ações que pode realizar para localizar a causa no código:

  • Verifique os registos de tarefas e veja se alguma operação demora muito tempo a ser concluída. Um exemplo seria um pedido de um recurso externo.
  • Certifique-se de que nenhum processo está a impedir a saída do programa. Alguns clientes podem criar os seus próprios threads e, se estes clientes não forem encerrados, o programa aguarda indefinidamente que estes threads sejam unidos.

Os pipelines iniciados diretamente que não usam um modelo não têm estas limitações. Por conseguinte, se o pipeline funcionou diretamente, mas não como um modelo, a utilização de um modelo pode ser a causa principal. Encontrar o problema no modelo e corrigi-lo pode resolver o problema.

Verifique se as opções de pipeline necessárias estão suprimidas

Quando usa modelos flexíveis, pode configurar algumas, mas não todas as opções de pipeline durante a inicialização do pipeline. Para mais informações, consulte a secção Falha ao ler o ficheiro de tarefas neste documento.

Utilizadores de Python: gestão de dependências

Se estiver a executar uma tarefa de modelo flexível do Python que forneça dependências adicionais num ficheiro requirements.txt, a tarefa pode não ser iniciada. Esta falha ocorre quando o download ou a instalação das dependências especificadas no ficheiro de requisitos demoram mais do que o tempo atribuído para iniciar o modelo flexível.

Para otimizar o desempenho da tarefa, pré-embale as dependências quando criar o modelo para evitar a necessidade de transferir ou instalar as dependências durante o lançamento do modelo. Para mais informações, consulte a secção Dependências de pacotes para Python em "Configure modelos flexíveis".

Falhas no lançamento de tarefas

A secção seguinte contém erros comuns que levam a falhas no lançamento de tarefas e passos para resolver ou solucionar os erros.

Problemas de arranque antecipado

Quando o processo de lançamento do modelo falha numa fase inicial, os registos normais do Flex Template podem não estar disponíveis. Para investigar problemas de arranque, ative o registo da porta série para a VM do Launcher de modelos.

Para ativar o registo para modelos Java, defina a opção enableLauncherVmSerialPortLogging como true. Para ativar o registo para modelos Python e Go, defina a opção enable_launcher_vm_serial_port_logging como true. Na Google Cloud consola, o parâmetro é indicado em Parâmetros opcionais como Ativar registo da porta série da VM do Launcher.

Pode ver os registos de saída da porta de série da VM do iniciador de modelos no Cloud Logging. Para encontrar os registos de uma VM de launcher específica, use a consulta resource.type="gce_instance" "launcher-number" onde number começa com a data atual no formato YYYMMDD.

A política da sua organização pode proibir a ativação do registo de saídas de portas de série.

Não foi possível ler o ficheiro de tarefas

Quando tenta executar uma tarefa a partir de um modelo flexível, a tarefa pode falhar com o seguinte erro:

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

Este erro ocorre quando as opções de inicialização do pipeline necessárias são substituídas. Quando usa modelos flexíveis, pode configurar algumas, mas não todas as opções do pipeline durante a inicialização do pipeline. Se os argumentos da linha de comandos exigidos pelo modelo flexível forem substituídos, a tarefa pode ignorar, substituir ou rejeitar as opções do pipeline transmitidas pelo iniciador de modelos. A tarefa pode não ser iniciada ou pode ser iniciada uma tarefa que não use o modelo flexível.

Para evitar este problema, durante a inicialização do pipeline, não altere as seguintes opções do pipeline no código do utilizador nem no ficheiro metadata.json:

Java

  • runner
  • project
  • jobName
  • templateLocation
  • region

Python

  • runner
  • project
  • job_name
  • template_location
  • region

Ir

  • runner
  • project
  • job_name
  • template_location
  • region

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

Quando tenta executar uma tarefa a partir de um modelo flexível, a tarefa pode falhar com o seguinte erro:

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

Este erro ocorre quando a conta de serviço predefinida do Compute Engine não tem todas as autorizações necessárias para executar um modelo flexível. Para ver a lista de autorizações necessárias, consulte o artigo Autorizações para executar um modelo flexível.

Autorização negada no recurso

Quando tenta executar uma tarefa a partir de um modelo flexível, a tarefa pode falhar com o seguinte erro:

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

Este erro ocorre quando a conta de serviço usada não tem autorizações para aceder aos recursos necessários para executar um modelo flexível.

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

Sinalização fornecida, mas não definida

Quando tenta executar um modelo flexível do Go com a opção de pipeline worker_machine_type, o pipeline falha com o seguinte erro:

flag provided but not defined: -machine_type

Este erro é causado por um problema conhecido nas versões 2.47.0 e anteriores do SDK Go do Apache Beam. Para resolver este problema, atualize para a versão 2.48.0 ou posterior do Apache Beam Go.

Não é possível obter o JAR do servidor de tarefas remoto

Se tentar executar uma tarefa a partir de um modelo flexível quando não tem ligação à Internet, a tarefa pode falhar com 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

Este erro ocorre porque a VM não consegue transferir o pacote Java do Apache Beam da Internet. Este pacote é obrigatório quando executa uma tarefa em vários idiomas através de um modelo flexível.

Para resolver este problema, faça uma das seguintes alterações:

  • Ligue-se à Internet. Quando tem ligação à Internet, o seu trabalho pode aceder ao ficheiro necessário.

  • Inclua o pacote Java do Apache Beam no seu diretório local para que a tarefa possa aceder ao mesmo localmente. Coloque o ficheiro 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 é possível obter o sistema de ficheiros do caminho especificado

Quando tenta executar uma tarefa a partir de um modelo flexível, a tarefa pode falhar com 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

Este erro ocorre quando a tarefa usa uma imagem de contentor de modelo flexível e a imagem de contentor não contém uma instalação Java.

Para resolver este problema, adicione a seguinte linha ao seu Dockerfile:

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

Este comando instala o Java no seu ambiente de contentores.

Atraso do iniciador do modelo flexível

Quando envia uma tarefa de modelo flexível, o pedido de tarefa é colocado numa fila do Spanner. O iniciador de modelos recebe a tarefa da fila do Spanner e, em seguida, executa o modelo. Quando o Spanner tem um atraso de mensagens, pode ocorrer um atraso significativo entre o momento em que envia a tarefa e o momento em que a tarefa é iniciada.

Para contornar este problema, inicie o modelo flexível a partir de uma região diferente.

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

Quando tenta usar a CLI gcloud para executar uma tarefa que usa um modelo fornecido pela 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

Este erro ocorre porque alguns modelos fornecidos pela Google não suportam as opções defaultSdkHarnessLog e defaultWorkerLog.

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

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

Depois de fazer esta alteração ao ficheiro de modelo, use o seguinte comando para executar o modelo.

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

Substitua os seguintes valores:

  • BUCKET_NAME: o nome do seu contentor do Cloud Storage
  • FILENAME: o nome do ficheiro de especificação do modelo

Os registos do Launcher de modelos flexíveis mostram a gravidade errada

Quando o lançamento de um modelo flexível personalizado falha, é apresentada a seguinte mensagem nos ficheiros de registo com a gravidade ERROR:

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

Normalmente, a causa principal da falha de lançamento aparece nos registos antes desta mensagem com a gravidade INFO. Embora este nível de registo possa estar incorreto, é esperado, porque o iniciador do modelo Flex não tem forma de extrair detalhes de gravidade das mensagens de registo produzidas pela aplicação Apache Beam.

Se quiser ver a gravidade correta de cada mensagem no registo do Launcher, configure o seu modelo para gerar registos no formato JSON em vez de texto simples. Esta configuração permite que o iniciador de modelos extraia a gravidade da mensagem de registo correta. Use a seguinte estrutura de mensagem:

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

Em Java, pode usar o registador Logback com uma implementação de anexador JSON personalizado. Para mais informações, consulte a configuração de exemplo do Logback e o código de exemplo do anexador JSON no GitHub.

Este problema só afeta os registos gerados pelo iniciador do modelo flexível quando o pipeline está a ser iniciado. Quando o lançamento é bem-sucedido e o pipeline está em execução, os registos produzidos pelos trabalhadores do Dataflow têm a gravidade adequada.

Os modelos fornecidos pela Google mostram a gravidade correta durante o lançamento do trabalho, porque os modelos fornecidos pela Google usam esta abordagem de registo JSON.