Soluciona problemas de plantillas de Flex

En esta página, se proporcionan sugerencias para la solución de problemas y estrategias de depuración que pueden resultarte útiles si usas plantillas de Flex de Dataflow Esta información puede ayudarte a detectar un tiempo de espera de sondeo, determinar el motivo por el que se ocurrió y corregir el problema.

Soluciona problemas de tiempos de espera de sondeo

En esta sección, se proporcionan pasos para identificar la causa de los tiempos de espera del sondeo.

Tiempos de espera de sondeo

El trabajo de plantilla de Flex puede mostrar el siguiente mensaje de error:

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

Este error puede ocurrir por los siguientes motivos:

  1. Se anuló la imagen base de Docker.
  2. La cuenta de servicio que completa ${service_account_email} no tiene los permisos necesarios.
  3. Las direcciones IP externas están inhabilitadas, y las VM no pueden conectarse con el conjunto de direcciones IP externas que usan las API y los servicios de Google.
  4. El programa que crea el grafo tarda demasiado en finalizar.
  5. Se reemplazan las opciones de canalización.
  6. Hay un problema con el archivo requirements.txt (solo Python).
  7. Se produjo un error transitorio.

Para resolver este problema, primero verifica si hay errores transitorios y verifica los registros del trabajo y vuelve a intentarlo. Si esos pasos no resuelven el problema, prueba los pasos que se indican a continuación para solucionarlo.

Verifica el punto de entrada de Docker

Prueba este paso si ejecutas una plantilla desde una imagen de Docker personalizada en lugar de usar una de las plantillas proporcionadas.

Verifica el punto de entrada del contenedor con el siguiente comando:

docker inspect $TEMPLATE_IMAGE

Se espera el siguiente resultado:

Java

/opt/google/dataflow/java_template_launcher

Python

/opt/google/dataflow/python_template_launcher

Si obtienes un resultado diferente, entonces se anula el punto de entrada de tu contenedor de Docker. Restablece $TEMPLATE_IMAGE a la configuración predeterminada.

Verifica los permisos de la cuenta de servicio

Verifica que la cuenta de servicio mencionada en el mensaje tenga los siguientes permisos:

  • Debe poder leer y escribir la ruta de acceso de Cloud Storage que completa ${file_path} en el mensaje.
  • Debe poder leer la imagen de Docker que completa ${image_url} en el mensaje.

Configura el Acceso privado a Google

Si las direcciones IP externas están inhabilitadas, debes permitir que las VMs de Compute Engine se conecten al conjunto de direcciones IP externas que usan las APIs y los servicios de Google. Habilita el acceso privado a Google en la subred que usa la interfaz de red de la VM.

Para obtener más información sobre la configuración, consulta Configura el Acceso privado a Google.

De forma predeterminada, cuando una VM de Compute Engine no tiene una dirección IP externa asignada a su interfaz de red, solo puede enviar paquetes a otros destinos con direcciones IP internas.

Comprueba si no se puede salir del programa de lanzamiento

El programa que construye la canalización debe finalizar antes de que se pueda iniciar. El error de sondeo podría indicar que tardó demasiado en hacerlo.

Puedes hacer algunas acciones para ubicar la causa en el código:

  • Verifica los registros del trabajo y verifica si alguna operación tarda mucho tiempo en completarse. Un ejemplo sería una solicitud de un recurso externo.
  • Asegúrate de que ningún subproceso esté bloqueando la salida del programa. Algunos clientes pueden crear sus propios subprocesos y, si estos clientes no se cierran, el programa espera de forma permanente a que se unan estos subprocesos.

Las canalizaciones que se inician directamente y que no usan una plantilla no tienen estas limitaciones. Por lo tanto, si la canalización funcionó directamente, pero no como una plantilla, el uso de una plantilla puede ser la causa raíz. Encontrar el problema en la plantilla y arreglarla podría resolver el problema.

Verifica si se suprimen las opciones de canalización necesarias

Cuando usas plantillas de Flex, puedes configurar algunas opciones de canalización, pero no todas, durante la inicialización de la canalización. Para obtener más información, consulta la sección No se pudo leer el archivo de trabajo en este documento.

Quita Apache Beam del archivo de requisitos (solo Python)

Si tu Dockerfile incluye un requirements.txt con apache-beam[gcp], quítalo del archivo y, luego, instálalo por separado. En el siguiente comando, se muestra cómo completar este paso:

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

Colocar Apache Beam en el archivo de requisitos puede causar tiempos de inicio largos, lo que a menudo provoca un tiempo de espera.

Sondea tiempos de espera para usar Python

Si ejecutas un trabajo de Dataflow mediante una plantilla de Flex y Python, el trabajo podría estar en cola durante un período, no ejecutarse y, luego, mostrar el siguiente error:

Timeout in polling

El archivo requirements.txt que se usa para instalar las dependencias necesarias genera el error. Cuando inicias un trabajo de Dataflow, todas las dependencias se habilitan primero para que las VMs de trabajador puedan acceder a estos archivos. Este proceso implica ndescargar y compilar cada dependencia indirecta y directa en el archivo requirements.txt. La compilación de algunas dependencias puede tardar varios minutos. En particular, PyArrow puede tardar en compilarse. PyArrow es una dependencia indirecta que usan Apache Beam y la mayoría de las bibliotecas cliente de Cloud.

Si deseas optimizar el rendimiento de tu trabajo, usa un Dockerfile o un contenedor personalizado para empaquetar previamente las dependencias. Para obtener más información, consulta Dependencias de paquetes en “Configura plantillas flexibles”.

Fallas de inicio de trabajo

La siguiente sección contiene errores comunes que generan fallas de inicio del trabajo y pasos para resolver los errores.

Problemas de inicio anticipado

Cuando el proceso de inicio de la plantilla falla en una etapa inicial, es posible que los registros normales de la plantilla de Flex no estén disponibles. Para investigar problemas de inicio, habilita los registros de puertos en serie para la VM del selector de plantillas.

A fin de habilitar el registro para las plantillas de Java, configura la opción enableLauncherVmSerialPortLogging como true. A fin de habilitar el registro para las plantillas de Python y Go, configura la opción enable_launcher_vm_serial_port_logging como true. En la consola de Google Cloud, el parámetro se enumera en Parámetros opcionales como Habilitar el registro de puertos en serie de VM del iniciador.

Puedes ver los registros de salidas del puerto en serie de la VM del selector de plantillas en Cloud Logging. Para buscar los registros de una VM de selector en particular, usa la consulta resource.type="gce_instance" "launcher-number", en la que number comienza con la fecha actual en el formato YYYMMDD.

La política de tu organización puede prohibir que habilites el registro de salidas del puerto en serie.

No se pudo leer el archivo de trabajo

Cuando intentas ejecutar un trabajo desde una plantilla de Flex, el trabajo podría fallar con uno de los siguientes errores:

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

O bien:

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

Este error se produce cuando se reemplazan las opciones de inicialización de canalización necesarias. Cuando usas plantillas de Flex, puedes configurar algunas opciones de canalización, pero no todas, durante la inicialización de la canalización. Si se reemplazan los argumentos de la línea de comandos requeridos por la plantilla flexible, el trabajo puede ignorar, anular o descartar las opciones de canalización que pasa el selector de plantillas. Es posible que el trabajo no se inicie o que se inicie un trabajo que no use la plantilla flexible.

Para evitar este problema, durante la inicialización de la canalización, no cambies las siguientes opciones de canalización en el código de usuario o en el archivo metadata.json:

Java

  • runner
  • project
  • jobName
  • templateLocation
  • region

Python

  • runner
  • project
  • job_name
  • template_location
  • region

Go

  • runner
  • project
  • job_name
  • template_location
  • region

Permiso denegado en el recurso

Cuando intentas ejecutar un trabajo desde una plantilla flexible, el trabajo podría fallar con el siguiente error:

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

Este error se produce cuando la cuenta de servicio que se usó no tiene los permisos para acceder a los recursos necesarios a fin de ejecutar una plantilla de Flex.

Para evitar este problema, verifica que la cuenta de servicio tenga los permisos necesarios. Ajusta los permisos de la cuenta de servicio según sea necesario.

Se proporcionó una marca, pero no se definió

Cuando intentas ejecutar una plantilla de Flex de Go con la opción de canalización worker_machine_type, la canalización falla con el siguiente error:

flag provided but not defined: -machine_type

Este error se debe a un problema conocido en las versiones 2.47.0 y anteriores del SDK de Apache Beam para Go. Para resolver este problema, actualiza a la versión 2.48.0 o posterior de Apache Beam para Go.

No se pudo recuperar el archivo JAR del servidor de trabajos remoto

Si intentas ejecutar un trabajo desde una plantilla de Flex cuando no estás conectado a Internet, el trabajo podría fallar con el siguiente error:

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 error se produce porque la VM no puede descargar el paquete de Java de Apache Beam de Internet. Este paquete es obligatorio cuando ejecutas un trabajo en varios idiomas con una plantilla de Flex.

Para resolver este problema, realiza uno de los siguientes cambios:

  • Conéctate a Internet Cuando te conectas a Internet, tu trabajo puede acceder al archivo requerido.

  • Incluye el paquete de Java de Apache Beam en tu directorio local para que tu trabajo pueda acceder a él de forma local. Crea el archivo en el siguiente directorio: /root/.apache_beam/cache/jars/. Por ejemplo, /root/.apache_beam/cache/jars/beam-sdks-java-io-expansion-service-SDK_VERSION.jar

No se puede obtener el sistema de archivos de la ruta de acceso especificada

Cuando intentas ejecutar un trabajo desde una plantilla flexible, el trabajo podría fallar con el siguiente error:

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 error se produce cuando la tarea usa una imagen de contenedor de plantilla de Flex y esta no contiene una instalación de Java.

Para resolver este problema, agrega la siguiente línea a tu Dockerfile:

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

Este comando instala Java en tu entorno de contenedor.

Demora del selector de plantillas de Flex

Cuando envías un trabajo de plantilla de Flex, la solicitud de trabajo va a una cola de Spanner. El selector de plantillas toma el trabajo de la cola de Spanner y, luego, ejecuta la plantilla. Cuando Spanner tiene mensajes pendientes, puede ocurrir un retraso significativo entre el momento en que envías el trabajo y el momento en que se inicia.

Para solucionar este problema, inicia tu plantilla de Flex desde una región diferente.

Los parámetros de la plantilla no son válidos

Cuando intentas usar gcloud CLI para ejecutar un trabajo que usa una plantilla proporcionada por Google, se produce el siguiente error:

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

Este error se produce porque algunas plantillas proporcionadas por Google no admiten las opciones defaultSdkHarnessLog y defaultWorkerLog.

Como solución alternativa, copia el archivo de especificación de plantilla en un bucket de Cloud Storage. Agrega los siguientes parámetros adicionales al archivo.

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

Después de realizar este cambio en el archivo de plantilla, usa el siguiente comando para ejecutar la plantilla.

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

Reemplaza los siguientes valores:

  • BUCKET_NAME: Es el nombre de tu bucket de Cloud Storage.
  • FILENAME: el nombre de tu archivo de especificación de plantilla

Los registros del selector de plantillas de Flex muestran una gravedad incorrecta

Cuando falla el inicio de una plantilla de Flex personalizada, aparece el siguiente mensaje en los archivos de registro con la gravedad ERROR:

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

La causa raíz de la falla de inicio suele aparecer en los registros anteriores a este mensaje con la gravedad INFO. Aunque este nivel de registro puede ser incorrecto, es esperable, ya que el selector de plantillas de Flex no tiene manera de extraer detalles de gravedad de los mensajes de registro que produce la aplicación de Apache Beam.

Si deseas ver la gravedad correcta de cada mensaje en el registro del selector, configura la plantilla para que genere registros en formato JSON en lugar de en texto sin formato. Esta configuración permite que el selector de plantillas extraiga la gravedad correcta del mensaje de registro. Usa la siguiente estructura de mensajes:

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

En Java, puedes usar el registrador de Logback con una implementación de agregador de JSON personalizado. Para obtener más información, consulta la configuración de ejemplo de Logback y el código de ejemplo del agregador de JSON en GitHub.

Este problema solo afecta a los registros generados por el selector de plantillas de Flex cuando se inicia la canalización. Cuando el lanzamiento se realiza de forma correcta y la canalización se ejecuta, los registros que producen los trabajadores de Dataflow tienen la gravedad adecuada.

Las plantillas que proporciona Google muestran la gravedad correcta durante el inicio del trabajo, ya que las plantillas que proporciona Google usan este enfoque de registro JSON.