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.

Resolver problemas de tempo limite de pesquisas

Esta seção apresenta as etapas para identificar a causa do tempo limite da enquete.

Tempo limite da enquete

Seu job de modelo flexível pode retornar a seguinte mensagem de erro:

Timeout in polling result file: ${file_path}.
Service account: ${service_account_email}
Image URL: ${image_url}
Troubleshooting guide at https://cloud.google.com/dataflow/docs/guides/common-errors#timeout-polling

Esse problema pode ocorrer pelos seguintes motivos:

  1. A imagem base do Docker foi modificada.
  2. A conta de serviço que preenche ${service_account_email} 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. O programa que cria o gráfico leva muito tempo para ser concluído.
  5. As opções de pipeline estão sendo substituídas.
  6. (Somente Python) Há um problema com o arquivo requirements.txt.
  7. Ocorreu um erro temporário.

Para resolver esse problema, primeiro verifique se há erros temporários nos registros do job e tente novamente. Se isso não resolver o problema, tente as etapas a seguir.

Verificar o ponto de entrada do Docker

Siga esta etapa se você estiver executando um modelo de uma imagem personalizada do Docker 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.

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 os registros do job e veja se alguma operação parece demorar muito para ser concluída. Um exemplo seria uma solicitação de um recurso externo.
  • 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 encerrados, o programa aguardará para sempre que essas linhas sejam mescladas.

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.

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.

Remover o Apache Beam do arquivo de requisitos (somente Python)

Se o Dockerfile incluir um requirements.txt com apache-beam[gcp], remova-o do arquivo e instale-o separadamente. O comando a seguir demonstra como concluir essa etapa:

RUN pip install apache-beam[gcp]
RUN pip install -U -r ./requirements.txt

Colocar o Apache Beam no arquivo de requisitos pode causar longos tempos de inicialização, geralmente resultando em um tempo limite.

Tempo limite de pesquisas ao usar o Python

Se você estiver executando um job do Dataflow usando modelo flexível e Python, o job poderá ser enfileirado por um período, apresentar falha e exibir o seguinte erro:

Timeout in polling

O arquivo requirements.txt usado para instalar as dependências necessárias causa o erro. Quando você inicia um job do Dataflow, todas as dependências são preparadas primeiro para tornar esses arquivos acessíveis às VMs do worker. Esse processo envolve o download e a compilação de todas as dependências diretas e indiretas no arquivo requirements.txt. Algumas dependências podem levar vários minutos para serem compiladas. Além disso, o PyArrow pode levar tempo para ser compilado. PyArrow é uma dependência indireta usada pelo Apache Beam e pela maioria das bibliotecas de cliente do Cloud.

Para otimizar o desempenho do job, use um Dockerfile ou um contêiner personalizado para pré-empacotar as dependências. Para mais informações, consulte Dependências de pacote 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 do 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 usando um modelo Flex, ele pode falhar com um dos seguintes erros:

Failed to read the job file : gs://dataflow-staging-REGION-PROJECT_ID/staging/template_launches/TIMESTAMP/job_object with error message: ...: Unable to open template file

Ou:

Failed to read the result file : gs://BUCKET_NAME with error message: (ERROR_NUMBER): Unable to open template file: gs://BUCKET_NAME

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

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.

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.