Cette page fournit des conseils de dépannage et des stratégies de débogage qui vous seront utiles si vous utilisez des modèles Flex Dataflow. Par défaut, le processus de lancement de modèle Flex dispose d'un délai avant expiration de 12 minutes. Ce processus de lancement inclut l'extraction de l'image de conteneur du modèle et l'exécution du code pour construire le graphique de la tâche. Si le lancement ne se termine pas dans ce délai de 12 minutes, la tâche échoue avec l'erreur "Timeout in polling result file" (Délai avant expiration dans le fichier de résultat d'interrogation). Ces informations peuvent vous aider à détecter une expiration du délai d'interrogation, à déterminer la raison de ce délai et à corriger le problème.
Erreurs de délai d'interrogation
Votre tâche peut renvoyer l'un des messages d'erreur suivants :
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
Ce problème peut survenir pour les raisons suivantes :
- L'image Docker de base a été remplacée.
- Le compte de service qui remplit SERVICE_ACCOUNT ne dispose pas de certaines autorisations nécessaires.
- Les adresses IP externes sont désactivées, et les VM ne peuvent pas se connecter à l'ensemble des adresses IP externes utilisées par les API et les services Google.
- La VM de lanceur ne peut pas résoudre ou accéder à gcr.io.
- Image de conteneur de modèle Flex volumineuse.
- L'exécution du programme en charge de la création du graphique est trop longue.
- L'exécution du code dans la VM de lanceur est trop longue.
- Erreurs intermittentes de réseau ou de Cloud Storage.
- Les options de pipeline sont en cours d'écrasement.
- Utilisateurs Python : l'installation ou la préproduction des dépendances prend trop de temps.
- Une erreur temporaire s'est produite.
Pour résoudre ce problème, commencez par rechercher des erreurs temporaires en consultant les journaux de la tâche et en réessayant.
Suivez les conseils de la section Problèmes de démarrage précoces pour activer la journalisation du port série, ce qui peut révéler des informations supplémentaires.
Si ces étapes ne permettent pas de résoudre le problème, essayez les étapes de dépannage suivantes.
Facultatif : Exécuter des modèles pour diagnostiquer plus précisément votre problème
Pour identifier plus précisément la cause de cette erreur parmi les raisons précédentes, utilisez les stratégies suivantes :
Exécutez le modèle WordCount fourni par Google. Veillez à fournir des paramètres propres à votre cas d'utilisation, tels que le sous-réseau d'un projet VPC partagé, l'adresse IP privée des VM de nœud de calcul et le compte de service de nœud de calcul Dataflow que vous souhaitez utiliser. Pour en savoir plus sur la fourniture de ces paramètres, consultez la documentation de référence de gcloud et la documentation de référence de l'API .
Si vous parvenez à terminer cette tâche, cela indique que la mise en réseau, les autorisations IAM et l'accès privé à Google sont probablement configurés correctement.
Suivez le guide de démarrage rapide Exécuter un pipeline à l'aide du générateur de tâches ,qui exécute la tâche en tant que modèle Flex. Si votre tâche échoue avant le lancement de la VM de nœud de calcul, accédez à la VM de lanceur et essayez de télécharger un exemple d'image Docker à l'aide d'une commande semblable à la suivante :
docker run --entrypoint /bin/bash -it gcr.io/dataflow-templates/2025-03-11-00_rc02/yaml-templateSi cette commande échoue, il peut y avoir un problème de mise en réseau lors du téléchargement des images. Dans ce cas, contactez votre équipe de mise en réseau interne.
Exécutez un modèle Flex fourni par Google et vérifiez le résultat. Si la tâche du modèle fourni par Google se termine correctement, cela indique que le problème est probablement lié à vos fichiers de code de modèle personnalisé spécifiques. Dans ce cas, vous devez continuer à résoudre les problèmes liés à votre code spécifique pour résoudre le problème.
Vérifier le point d'entrée Docker
Suivez cette étape si vous exécutez un modèle à partir d'une image Docker personnalisée au lieu d'utiliser l'un des modèles fournis.
Recherchez le point d'entrée du conteneur à l'aide de la commande suivante :
docker inspect $TEMPLATE_IMAGE
Le résultat suivant est attendu :
Java
/opt/google/dataflow/java_template_launcher
Python
/opt/google/dataflow/python_template_launcher
Si vous obtenez un autre résultat, le point d'entrée de votre conteneur Docker est remplacé. Restaurez la valeur par défaut de $TEMPLATE_IMAGE.
Vérifier les autorisations du compte de service
Vérifiez que le compte de service mentionné dans le message dispose des autorisations suivantes :
- Il doit pouvoir lire et écrire le chemin d'accès Cloud Storage qui remplit
${file_path}dans le message. - Il doit pouvoir lire l'image Docker qui remplit
${image_url}dans le message.
Configurer l'accès privé à Google
Si les adresses IP externes sont désactivées, vous devez autoriser les VM Compute Engine à se connecter à l'ensemble des adresses IP externes utilisées par les API et services Google. Activez l'accès privé à Google sur le sous-réseau utilisé par l'interface réseau de la VM.
Pour en savoir plus sur la configuration, consultez la section Configurer l'accès privé à Google.
Par défaut, lorsqu'une VM Compute Engine n'a pas d'adresse IP externe attribuée à son interface réseau, elle ne peut envoyer des paquets qu'à d'autres destinations d'adresses IP internes.
Problèmes d'accès à GCR.io
Les VM de lanceur de modèle Flex nécessitent un accès à gcr.io pour extraire un conteneur d'agent de journalisation
(gcr.io/dataflow-templates-base/template-launcher-logger-distroless). Cet
agent est responsable de la diffusion des journaux du lanceur vers Cloud Logging. Si la VM de lanceur ne peut pas résoudre ou se connecter à gcr.io, le processus de démarrage peut cesser de répondre, ce qui entraîne un délai d'interrogation.
Ce problème peut se produire même si l'image de votre modèle personnalisé est stockée dans Artifact Registry, car l'agent de journalisation est toujours extrait de gcr.io.
Pour diagnostiquer et résoudre ce problème, procédez comme suit :
Activer la journalisation du port série : suivez les étapes de la section Problèmes de démarrage précoces. Si vous constatez que le processus
cloud-initest bloqué ou qu'il existe des erreurs liées àgcr-wait-online.service, il s'agit probablement d'un problème de DNS ou de mise en réseau.Se connecter à la VM de lanceur via SSH : utilisez la commande
gcloud compute sshpour vous connecter à la VM de lanceur pendant son exécution :gcloud compute ssh launcher-JOB_ID --tunnel-through-iapRemplacez
JOB_IDpar l'ID de votre job Dataflow.Vérifier la résolution DNS : exécutez les commandes suivantes dans la VM de lanceur :
curl -I https://gcr.ioSi la commande échoue avec une
"Could not resolve host"erreur, votre configuration DNS ne comporte pas d'entrée pourgcr.io.Vérifier les services de démarrage bloqués : examinez le journal de sortie
cloud-init:sudo cat /var/log/cloud-init-output.logRecherchez les messages indiquant que le processus attend le réseau ou que
gcr.iodevienne accessible.
Assurez-vous également que les paramètres DNS de votre VPC autorisent la résolution de gcr.io. Dans certaines configurations de réseau privé, vous devrez peut-être ajouter un
enregistrement DNS A spécifique pour gcr.io pointant vers les plages d'adresses IP des API Google limitées ou
des API Google privées.
Image de conteneur volumineuse
Si l'image de conteneur de votre modèle Flex est volumineuse, l'extraction et le lancement du modèle peuvent dépasser le délai avant expiration par défaut de 12 minutes, ce qui entraîne l'échec de la tâche.
Pour atténuer le problème, essayez les stratégies suivantes :
- Optimisez votre image pour réduire sa taille afin d'accélérer le processus d'extraction.
- Utilisez l'option
--launcher-machine-typepour sélectionner un type de machine avec plus de cœurs de processeur, ce qui permet d'extraire l'image plus rapidement et d'accélérer le lancement. - Utilisez l'option
--launcher-vm-timeout-secspour spécifier une durée de délai avant expiration plus longue pour la VM de lanceur, ce qui lui permet de dépasser la limite par défaut de 12 minutes.
Vérifier si le programme de lancement a un problème pour se fermer
Le programme qui construit le pipeline doit se fermer avant que le pipeline puisse démarrer. L'erreur d'interrogation peut indiquer que l'opération est trop longue.
Voici quelques actions que vous pouvez effectuer pour identifier la cause dans le code :
- Assurez-vous qu'aucun thread ne bloque la fermeture du programme. Certains clients peuvent créer leurs propres threads. Si ces clients ne sont pas arrêtés, le programme attend indéfiniment leur jonction.
- Dans le code qui définit votre pipeline, n'utilisez pas
waitUntilFinish(pour Java) niwait_until_finish(pour Python). Ces fonctions empêchent le programme de se fermer, ce qui empêche le modèle Flex de lancer le pipeline.
Les pipelines lancés directement qui n'utilisent pas de modèle ne sont pas soumis à ces limites. Par conséquent, si le pipeline fonctionne directement, mais pas en tant que modèle, alors l'utilisation d'un modèle peut être la cause du problème. La recherche et la résolution du problème dans le modèle peuvent résoudre le problème.
Code de longue durée dans la VM de lanceur
Si l'exécution du code de votre programme principal prend trop de temps, le modèle Flex peut expirer avant le lancement du pipeline. Cela peut se produire si le code effectue des calculs complexes ou des appels synchrones à des ressources externes lors de l'initialisation.
Pour diagnostiquer ce problème, vérifiez les journaux de la tâche pour toute opération dont l'exécution prend beaucoup de temps. Par exemple, les requêtes de ressources externes, les recherches de données volumineuses ou la logique d'initialisation lourde que vous pouvez déplacer vers la phase d'exécution du pipeline.
Erreurs intermittentes de réseau ou de Cloud Storage
Des erreurs intermittentes "Timeout in polling result file" (Délai avant expiration dans le fichier de résultat d'interrogation) ou "Failed to read the result file" (Échec de la lecture du fichier de résultat) peuvent se produire en raison d'une latence réseau élevée ou de problèmes temporaires avec l'API Cloud Storage. La contention réseau chronique dans votre VPC, en particulier dans le chemin d'accès privé à Google, entraîne souvent des latences de 400 à 500 ms.
Une erreur "Timeout in polling result file" (Délai avant expiration dans le fichier de résultat d'interrogation) est généralement un échec lent, tandis qu'une erreur "Failed to read the result file" (Échec de la lecture du fichier de résultat) est un échec rapide, mais les deux indiquent souvent le même problème de connectivité sous-jacent.
Pour diagnostiquer ces échecs intermittents :
- Vérifiez la latence réseau : surveillez la latence réseau dans votre VPC. Une latence élevée et soutenue peut entraîner des délais avant expiration lorsque la VM de lanceur tente d'écrire ou de lire le fichier de résultat de la tâche à partir de Cloud Storage.
Surveillez les métriques de l'API Cloud Storage :
Dans la Google Cloud console, accédez au tableau de bord API et services.
Filtrez et sélectionnez l'API Cloud Storage.
Consultez les graphiques pour le trafic (octets envoyés et reçus) et le taux d'erreur.
Recherchez les pics d'erreurs 5xx (telles que les erreurs 503) qui correspondent à l'heure exacte des échecs de tâches.
Si vous identifiez des pics d'erreurs ou une latence élevée, examinez les performances réseau de votre VPC ou contactez Cloud Customer Care pour obtenir de l'aide en cas d'interruption potentielle du service.
Vérifier si les options de pipeline requises sont supprimées
Lorsque vous utilisez des modèles Flex, vous pouvez configurer certaines options de pipeline lors de l'initialisation du pipeline, mais pas toutes. Pour en savoir plus, consultez la section Échec de la lecture du fichier de job de ce document.
Utilisateurs Python : gestion des dépendances
Si vous exécutez une tâche de modèle Flex Python qui fournit des dépendances supplémentaires dans un fichier requirements.txt, votre tâche peut échouer au lancement. Cet échec se produit lorsque le téléchargement ou l'installation des dépendances spécifiées dans le fichier de exigences prend plus de temps que le temps alloué au lancement du modèle Flex.
Pour optimiser les performances de votre tâche, pré-empaquetez les dépendances lors de la création de votre modèle afin d'éviter de devoir télécharger ou installer les dépendances lors du lancement du modèle. Pour en savoir plus, consultez la section Empaqueter les dépendances pour Python de la page "Configurer des modèles Flex".
Échecs de lancement de tâches
La section suivante contient des erreurs courantes qui entraînent des échecs de lancement de tâches et des étapes pour les résoudre ou pour le dépannage.
Problèmes de démarrage précoces
Lorsque le processus de lancement de modèle échoue de façon précoce, les journaux de modèle Flex standards peuvent ne pas être disponibles. Pour enquêter sur les problèmes de démarrage, activez la journalisation des ports série pour la VM du lanceur de modèles.
Pour activer la journalisation des modèles Java, définissez l'option enableLauncherVmSerialPortLogging sur true. Pour activer la journalisation pour les modèles Python et Go, définissez l'option enable_launcher_vm_serial_port_logging sur true. Dans la Google Cloud console, le paramètre est
répertorié dans Paramètres facultatifs comme Activer la journalisation du port série des VM de lanceur d'applications.
Vous pouvez afficher les journaux des données de sortie du port série des VM de lanceur de modèles dans Cloud Logging. Pour trouver les journaux d'une VM de lanceur spécifique, utilisez la requête resource.type="gce_instance" "launcher-number", où number commence par la date actuelle au format YYYMMDD.
Votre règle d'administration peut vous interdire d'activer la journalisation des données en sortie du port série.
Échec de la lecture du fichier de tâche
Lorsque vous essayez d'exécuter une tâche à partir d'un modèle Flex, votre tâche peut échouer avec l'erreur suivante:
Failed to read the job file : gs://dataflow-staging-REGION-PROJECT_ID/staging/template_launches/TIMESTAMP/job_object...
Cette erreur se produit lorsque les options d'initialisation de pipeline nécessaires sont écrasées. Lorsque vous utilisez des modèles Flex, vous pouvez configurer certaines options de pipeline lors de l'initialisation du pipeline, mais pas toutes. Si les arguments de ligne de commande requis par le modèle Flex sont écrasés, la tâche peut ignorer, remplacer ou supprimer les options de pipeline transmises par le lanceur de modèles. La tâche peut échouer au lancement ou une tâche qui n'utilise pas le modèle Flex peut être lancée.
Pour éviter ce problème, ne modifiez pas les options de pipeline suivantes dans le code utilisateur ou dans le fichier metadata.json lors de l'initialisation du pipeline :
Java
runnerprojectjobNametemplateLocationregion
Python
runnerprojectjob_nametemplate_locationregion
Go
runnerprojectjob_nametemplate_locationregion
Échec de la lecture du fichier de résultat
Lorsque vous essayez d'exécuter une tâche à partir d'un modèle Flex, votre tâche peut échouer avec l'erreur suivante:
Failed to read the result file : gs://BUCKET_NAME...
Cette erreur se produit lorsque le compte de service Compute Engine par défaut ne dispose pas de toutes les autorisations nécessaires pour exécuter un modèle Flex.
Pour obtenir la liste des autorisations requises, consultez la section Autorisations nécessaires pour exécuter un modèle Flex Template.
Cette erreur peut également être causée par une latence réseau intermittente ou des problèmes liés à l'API Cloud Storage. Pour en savoir plus, consultez la section Erreurs intermittentes de réseau ou de Cloud Storage errors.
Autorisation refusée pour la ressource
Lorsque vous essayez d'exécuter une tâche à partir d'un modèle Flex, votre tâche peut échouer avec l'erreur suivante:
Permission "MISSING_PERMISSION" denied on resource "projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME" (or it may not exist).
Cette erreur se produit lorsque le compte de service utilisé n'est pas autorisé à accéder aux ressources nécessaires pour exécuter un modèle Flex.
Pour éviter ce problème, vérifiez que le compte de service dispose des autorisations requises. Ajustez les autorisations du compte de service si nécessaire.
Option fournie, mais non définie
Lorsque vous essayez d'exécuter un modèle Flex Go avec l'option de pipeline worker_machine_type, le pipeline échoue avec l'erreur suivante :
flag provided but not defined: -machine_type
Cette erreur est due à un problème connu dans les versions 2.47.0 et antérieures du SDK Apache Beam pour Go. Pour résoudre ce problème, mettez à niveau Apache Beam Go vers la version 2.48.0 ou une version ultérieure.
Impossible de récupérer le fichier JAR du serveur de tâches distant
Si vous essayez d'exécuter une tâche à partir d'un modèle Flex alors que vous n'êtes pas connecté à Internet, votre tâche peut échouer avec l'erreur suivante :
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
Cette erreur se produit, car la VM ne parvient pas à télécharger le package Java Apache Beam depuis Internet. Ce package est requis lorsque vous exécutez une tâche multilingue à l'aide d'un modèle Flex.
Pour résoudre ce problème, effectuez l'une des modifications suivantes :
Connectez-vous à Internet. Lorsque vous êtes connecté à Internet, votre tâche peut accéder au fichier requis.
Incluez le package Java Apache Beam dans votre répertoire local afin que votre tâche puisse y accéder localement. Créez le fichier dans le répertoire suivant :
/root/.apache_beam/cache/jars/Exemple :/root/.apache_beam/cache/jars/beam-sdks-java-io-expansion-service-SDK_VERSION.jar.
Impossible d'obtenir le système de fichiers à partir du chemin d'accès spécifié
Lorsque vous essayez d'exécuter une tâche à partir d'un modèle Flex, votre tâche peut échouer avec l'erreur suivante:
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
Cette erreur se produit lorsque la tâche utilise une image de conteneur de modèle Flex et que l'image de conteneur ne contient pas d'installation Java.
Pour résoudre ce problème, ajoutez la ligne suivante à votre fichier Dockerfile :
sh
RUN apt-get update && apt-get install -y openjdk-17-jdk
Cette commande installe Java dans votre environnement de conteneur.
Épuisement des ressources de la VM de lanceur
Lorsque vous essayez d'exécuter une tâche à partir d'un modèle Flex, votre tâche peut échouer avec l'erreur suivante :
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.
Le nom de la VM launcher-ID représente le nom de la VM de lanceur. La VM de lanceur est chargée de collecter les ressources de la tâche, telles que le code et l'image du modèle, avant de créer et d'envoyer le graphique de la tâche au service Dataflow pour démarrer le travail.
Si vous ne spécifiez pas le paramètre launcherMachineType, Dataflow choisit un type de machine par défaut pour la VM de lanceur. Ce choix est indépendant du machineType du nœud de calcul. Des erreurs d'épuisement des ressources peuvent se produire si ce type de machine par défaut n'est pas disponible dans la région ou la zone de la tâche.
Pour résoudre ce problème, utilisez l'une des stratégies suivantes :
- Remplacez le type de machine du lanceur par un autre type
de machine et réessayez la tâche.
- API REST : définissez
launchParameter.environment.launcherMachineTypedans la méthodeflexTemplates.launch. - gcloud CLI : définissez l'
--launcher-machine-typeindicateur dans lagcloud dataflow flex-template runcommande.
- API REST : définissez
- Lancez votre modèle Flex à partir d'une autre région.
Délai du lanceur de modèles Flex
Lorsque vous envoyez un job de modèle Flex, la requête du job est placée dans une file d'attente Spanner. Le lanceur de modèles récupère la tâche dans la file d'attente Spanner, puis exécute le modèle. Lorsqu'un backlog de messages est présent dans Spanner, un délai important peut s'écouler entre le moment où vous envoyez le job et celui où le job est lancé.
Pour contourner ce problème, lancez votre modèle Flex à partir d'une autre région.
Les paramètres du modèle ne sont pas valides
Lorsque vous essayez d'utiliser gcloud CLI pour exécuter une tâche qui utilise un modèle fourni par Google, l'erreur suivante se produit :
ERROR: (gcloud.beta.dataflow.flex-template.run) INVALID_ARGUMENT: The template
parameters are invalid. Details: defaultSdkHarnessLogLevel: Unrecognized
parameter defaultWorkerLogLevel: Unrecognized parameter
Cette erreur se produit, car certains modèles fournis par Google ne sont pas compatibles avec les options defaultSdkHarnessLog et defaultWorkerLog.
Pour résoudre ce problème, utilisez la méthode appropriée pour votre type de modèle.
Modèles Flex
Pour les modèles Flex, utilisez l'option --additional-pipeline-options pour transmettre les options de pipeline sous forme de chaîne. Par exemple, à l'aide de la gcloud dataflow
flex-template run commande :
gcloud dataflow flex-template run JOB_NAME \
--template-file-gcs-location=GCS_TEMPLATE_PATH \
--additional-pipeline-options=defaultSdkHarnessLogLevel=WARN,defaultWorkerLogLevel=WARN
Remplacez les valeurs suivantes :
JOB_NAME: nom de votre tâche DataflowGCS_TEMPLATE_PATH: chemin d'accès Cloud Storage au fichier de modèle
Modèles classiques
Pour les modèles classiques, la solution consiste à copier le fichier de spécification du modèle dans un bucket Cloud Storage et à ajouter les paramètres supplémentaires suivants au fichier.
"metadata": {
...
"parameters": [
...,
{
"name": "defaultSdkHarnessLogLevel",
"isOptional": true,
"paramType": "TEXT"
},
{
"name": "defaultWorkerLogLevel",
"isOptional": true,
"paramType": "TEXT"
}
]
}
Après avoir apporté cette modification au fichier de modèle, utilisez l'option suivante lorsque vous exécutez le modèle.
--gcs-location=gs://BUCKET_NAME/FILENAME
Remplacez les valeurs suivantes :
BUCKET_NAME: nom de votre bucket Cloud StorageFILENAME: nom du fichier de spécification de modèle
Les journaux du lanceur de modèle Flex affichent une gravité incorrecte
Lorsqu'un lancement de modèle Flex personnalisé échoue, le message suivant s'affiche dans les fichiers journaux avec la gravité ERROR :
ERROR: Error occurred in the launcher container: Template launch failed. See console logs.
La cause première de l'échec du lancement apparaît généralement dans les journaux avant ce message avec le niveau de gravité INFO. Bien que ce niveau de journalisation puisse être incorrect, il est normal que le lanceur de modèle Flex ne puisse pas extraire les détails de gravité des messages de journal générés par l'application Apache Beam.
Si vous souhaitez afficher le niveau de gravité correct pour chaque message dans le journal du lanceur, configurez votre modèle pour générer des journaux au format JSON plutôt qu'au format texte brut. Cette configuration permet au lanceur de modèles d'extraire le niveau de gravité correct des messages de journal. Utilisez la structure de messages suivante :
{
"message": "The original log message",
"severity": "DEBUG/INFO/WARN/ERROR"
}
En Java, vous pouvez utiliser l'enregistreur Logback avec une implémentation appender JSON personnalisée. Pour en savoir plus, consultez l'exemple de configuration Logback et l'exemple de code d'appender JSON dans GitHub.
Ce problème ne concerne que les journaux générés par le lanceur de modèle Flex lors du lancement du pipeline. Une fois le lancement réussi et le pipeline en cours d'exécution, la gravité des journaux produits par les nœuds de calcul Dataflow est appropriée.
Les modèles fournis par Google affichent le niveau de gravité correct lors du lancement du job, car ils utilisent cette approche de journalisation JSON.