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:
- A imagem base do Docker foi modificada.
- A conta de serviço que preenche
${service_account_email}não tem algumas permissões necessárias. - 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.
- O programa que cria o gráfico leva muito tempo para ser concluído.
- As opções de pipeline estão sendo substituídas.
- (Somente Python) Há um problema com o arquivo
requirements.txt. - 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 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 with error message: ...: Unable to open template file
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
runnerprojectjobNametemplateLocationregion
Python
runnerprojectjob_nametemplate_locationregion
Go
runnerprojectjob_nametemplate_locationregion
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 with error message: (ERROR_NUMBER): Unable to open template 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.
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 StorageFILENAME: 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.