MemoriaGCP

tekio.org

Diagnostiquer un pipeline Dataflow

Un job Dataflow lent ou bloqué se diagnostique toujours dans le même ordre : quelle étape retient le pipeline, pourquoi elle ne suit pas (clé chaude, sink lent, workers saturés, mémoire), puis ce qui empêche le service de corriger seul (quota, plafond de workers, parallélisme). L'interface de surveillance répond aux deux premières questions, les journaux à la troisième. La conception du pipeline (fenêtres, doublons, données en retard) relève de Streaming.

Symptôme ? retard qui croît OOM, worker perdu job en échec CPU des workers ? saturé partout inégal faible Message du job ? quota, IP, zone accès, délai Workers, quota Clé chaude Sink, fusion Threads, RAM Quotas, région IAM, réseau
Arbre de diagnostic : du symptôme à la cause probable

Lire l'interface de surveillance

Dataflow découpe le pipeline en étapes (stages) : plusieurs transformations (steps) fusionnées s'exécutent ensemble, sans matérialiser les données entre elles. Les métriques se lisent par étape, pas par transformation.

Vue (console Dataflow → Jobs) Ce qu'on y lit Question qu'elle tranche
Graphe du job Transformations, débit et temps passé par étape ; panneau d'informations de l'étape sélectionnée Où passe le temps ? Quelle étape est signalée en goulot ?
Détails d'exécution Stage progress (fraîcheur par étape en flux, avancement et chemin critique en lots), Stage workflow, Worker progress (lots) Quelle étape est lente ou bloquée ? Quel worker traîne ?
Métriques du job Fraîcheur des données, latence système, backlog (secondes et octets), CPU et mémoire des workers, parallélisme, E/S des sources et sinks Le pipeline suit-il le débit entrant ?
Autoscaling Nombre de workers, cible, raison des décisions, indice d'utilisation actif ou non Pourquoi le service n'ajoute-t-il pas de workers ?
Recommandations Diagnostics de Dataflow Insights (performance, coût, erreurs), conservés 30 jours Le service a-t-il déjà identifié la cause ?
Journaux (onglet Diagnostics) Erreurs regroupées, dont les erreurs de mémoire, avec leur fréquence Quelle erreur revient, et depuis quand ?
Échantillonnage des données Éléments réels observés à chaque étape La donnée a-t-elle la forme attendue ?

Trois signaux suffisent à situer un pipeline en continu :

  • Fraîcheur des données (data freshness) : écart entre l'horodatage d'un élément et son traitement. Une courbe qui monte en continu signale un débit inférieur au débit entrant.
  • Latence système (system lag, system_lag et per_stage_system_lag) : durée maximale pendant laquelle un élément attend ou est en cours de traitement ; elle désigne l'étape lente.
  • Backlog (backlog_bytes, backlog_elements) : volume non traité par étape ; en Streaming Engine, backlog seconds estime le temps de résorption à débit constant.

Leur combinaison oriente le diagnostic : fraîcheur et backlog qui croissent ensemble, le pipeline ne progresse plus ; fraîcheur qui croît avec un backlog stable, des work items sont bloqués ; latence système basse, fraîcheur et backlog en hausse avec des CPU peu chargés, le pipeline s'étouffe sous un trop grand nombre de clés.

Le détecteur de goulots (bottleneck detector) signale en flux tout composant (brassage, DoFn, écriture d'état) en retard de plus de cinq minutes et le classe en quatre états : bloqué, en retard croissant, en retard stable, en rattrapage. Un retard se propage vers l'amont : plusieurs étapes paraissent lentes alors qu'une seule est en cause, celle que le détecteur désigne.

Symptômes, causes, remèdes

Symptôme Causes à vérifier Remède
Retard qui croît, CPU saturé partout Plafond max_num_workers atteint ; quota de vCPU, d'instances ou d'adresses IP externes ; zone à court de ressources Relever le plafond (en vol pour Streaming Engine) ; demander un quota (Quotas et limites) ; machine plus grosse ou autre région
CPU très inégal entre workers Clé chaude : une clé surreprésentée traitée par un seul thread Journaliser la clé, redistribuer (suffixe aléatoire), with_hot_key_fanout sur l'agrégat
Retard qui croît, CPU faible et homogène Sink ou API externe lents (429, quotaExceeded dans les journaux des workers) ; trop peu de clés ou partitions Kafka ; fusion qui colle une étape très démultipliée à une source peu parallèle Quota du sink, écritures groupées, délais d'expiration sur les appels ; Reshuffle après la source ou le ParDo qui démultiplie
Étape bloquée, message Operation ongoing DoFn bloqué, appel externe sans délai d'expiration, lecture ou écriture d'état volumineuse Pile d'appels dans le journal ; Cloud Profiler ; délais d'expiration et appels groupés (GroupIntoBatches)
Traînard (straggler) signalé dans les détails d'exécution Clé chaude, worker lent (en lots, Dataflow le remédie seul par une maintenance simulée), cause indéterminée Suivre le lien vers les journaux du worker à l'instant détecté ; mêmes remèdes que ci-dessus
Erreurs de mémoire, workers perdus Trop de threads pour la mémoire, side input volumineuse, valeurs d'une clé accumulées dans une liste, gros fichier ouvert dans un DoFn Moins de threads, machine à mémoire élevée, side input réduite, Combine plutôt que GroupByKey puis boucle
Pas de montée en charge malgré le backlog Backlog trop bref, parallélisme limité par les clés, fichiers de staging supprimés par une règle de cycle de vie du bucket, quota, mise à jour d'autoscaling vertical en cours Voir « Autoscaling qui ne suit pas » ci-dessous
Doublons ou données manquantes en flux Mode at-least-once ; retard autorisé nul qui jette les éléments tardifs Voir Streaming : mode exactly-once, allowed_lateness, dédoublonnage en aval
Job par lots en échec au lancement Réseau, permissions, quotas Selon le message du journal du job, voir « Échecs au lancement » ci-dessous

En lots, un élément qui échoue quatre fois fait échouer le job (A work item has failed 4 times, seuil non réglable). En flux, le lot qui le contient est relancé indéfiniment et bloque le pipeline sans le faire échouer. Tout pipeline en continu a besoin d'une sortie d'erreurs (dead-letter) codée dans le pipeline.

Clés chaudes et fusion

Dataflow journalise la présence d'une clé chaude, pas sa valeur. L'option de débogage l'écrit dans les journaux : --dataflow_service_options=enable_hot_key_logging en Python, --hotKeyLoggingEnabled=true en Java. Les entrées se retrouvent avec le filtre jsonPayload.logger="org.apache.beam.runners.dataflow.worker.HotKeyLogger", qui peut servir de base à une alerte sur journal.

import apache_beam as beam

# Agrégat par clé : Dataflow combine déjà localement avant le brassage (en lots surtout).
# with_hot_key_fanout ajoute un niveau intermédiaire qui répartit une clé chaude sur 16 sous-clés.
totaux = ventes | beam.CombinePerKey(sum).with_hot_key_fanout(16)

# Source peu parallèle suivie d'un ParDo qui démultiplie : casser la fusion pour répartir la suite.
lignes = (
    fichiers
    | beam.ParDo(ExtraireLignes())   # quelques fichiers, des millions de lignes
    | beam.Reshuffle()               # empêche la fusion avec l'étape suivante
    | beam.ParDo(Enrichir())
)

Dataflow effectue lui-même la combinaison partielle locale (combiner lifting) avant l'agrégation : ne pas la recoder à la main. En flux, il peut y renoncer pour privilégier la latence. Elle suppose une fonction de combinaison : un GroupByKey suivi d'une boucle Python ramène toutes les valeurs de la clé sur un seul thread, et souvent en mémoire. Quand la clé chaude n'est pas un agrégat, la redistribuer par un ParDo qui ajoute un suffixe aléatoire (salage), agréger, puis retirer le suffixe et agréger une seconde fois. À l'inverse, trop de clés coûte aussi : un Reshuffle sans nombre de seaux (withNumBuckets en Java) peut en créer des millions, chacune traitée en petits lots.

Mémoire

Chaque worker exécute plusieurs threads qui partagent sa mémoire. En Python, un processus SDK tourne par vCPU, avec 12 threads en flux ; chaque processus garde sa propre copie des side inputs et des modèles chargés. En Java et Go, un seul processus par worker, jusqu'à 300 ou 500 threads en flux selon le runner.

  • Réduire les threads : --number_of_worker_harness_threads (Python, Go), --numberOfWorkerHarnessThreads (Java). En lots, moins que le nombre de vCPU ; en flux, diviser par deux et observer (6, 3, 1 en Python).
  • Plus de mémoire par vCPU : type à mémoire élevée (--machine_type=n2-highmem-4 en Python) ou type personnalisé à mémoire étendue ; le nombre de threads reste le même.
  • Réduire les side inputs : vues itérables (AsIterable, AsMultimap) plutôt que AsList ; avec Streaming Engine, une side input est limitée à 80 Mo et stockée hors des workers.
  • Un seul processus SDK Python par worker (--experiments=no_use_multiple_sdk_containers) : partage un gros modèle entre threads, en dernier recours.

Les erreurs se lisent dans l'onglet Diagnostics, dans les journaux des workers, ou dans les journaux système avec la requête "out of memory" OR "OutOfMemory" OR "Shutting down JVM".

Autoscaling qui ne suit pas

  • Plafond : max_num_workers borne l'autoscaling horizontal (100 par défaut avec Streaming Engine, 1 000 au maximum). Avec Streaming Engine, le plafond et le plancher se modifient sans arrêter le job : gcloud dataflow jobs update-options --region=REGION --max-num-workers=50 JOB_ID.
  • Quotas : Dataflow ne crée pas plus de workers que le quota d'instances, de vCPU et d'adresses IP externes du projet ne l'autorise, tous jobs confondus. gcloud compute regions describe REGION affiche la consommation régionale.
  • Parallélisme : si le backlog est élevé mais que les clés disponibles sont peu nombreuses, ajouter des workers ne servirait à rien et le service ne le fait pas.
  • Sans Streaming Engine : les disques persistants, en nombre égal à max_num_workers, se répartissent équitablement ; le job ne descend que par paliers qui gardent le même nombre de disques sur chaque worker, et jamais sous max_num_workers / 15.
  • Réglages (Streaming Engine) : indice d'utilisation worker_utilization_hint (cible CPU entre 0,1 et 0,9, 0,8 par défaut) ; palier de latence low_latency (backlog visé sous 15 s, par défaut), medium_latency (2 min) ou high_latency (10 min), modifiable en vol par --latency-tier ; indice de parallélisme max_active_bundles_per_worker pour les transformations longues peu consommatrices de CPU (inférence sur GPU).

Échecs au lancement

Un job qui échoue avant de traiter une donnée échoue presque toujours sur l'environnement : réseau, identité ou capacité. Le journal du job donne le message ; le journal worker-startup détaille le démarrage des VM.

Message Cause Action
ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS Type de machine momentanément indisponible dans la zone Autre type de machine, autre région, ou resource hints min_ram / cpu_count pour laisser Dataflow choisir
IP_SPACE_EXHAUSTED Sous-réseau trop petit pour le nombre de workers Plafond de workers, sous-réseau agrandi ou dédié (Concevoir le réseau)
The project quota may have been exceeded or access control policies may be preventing the operation Quota Compute Engine, ou politique d'organisation (adresses IP externes interdites, zones restreintes) Journal d'activité des VM ; --no_use_public_ips si les IP externes sont interdites
Permissions verification for controller service account failed Le compte de service des workers n'a pas roles/dataflow.worker Accorder le rôle ; l'utilisateur qui lance a besoin de roles/dataflow.developer et roles/iam.serviceAccountUser
Staged package...is inaccessible Bucket de staging purgé par une règle de cycle de vie, ou dans un autre projet sans droits Bucket de staging sans suppression automatique, lisible par le compte des workers
DEADLINE_EXCEEDED, Server Unresponsive Règle de pare-feu manquante entre workers (TCP 12345 en flux, 12346 en lots, sans Streaming Engine ni Dataflow Shuffle) Règle d'entrée sur ces ports entre VM portant l'étiquette réseau dataflow
Connection timed out vers un service externe Workers sans IP externe sans Cloud NAT, ou avec IP externe alors que la sortie doit passer par Cloud NAT Workers sans IP externe, Cloud NAT pour Internet, accès privé à Google sur le sous-réseau pour les API Google

--no_use_public_ips (Python) ou --usePublicIps=false (Java) supprime les adresses externes des workers : plus de surface exposée, plus de quota d'IP externes consommé. Le sous-réseau doit alors avoir l'accès privé à Google activé, sans quoi les workers n'atteignent ni Cloud Storage ni les API de Dataflow. Sans accès à Internet, les dépendances Python ne s'installent plus depuis PyPI au démarrage : les fournir au staging ou dans un conteneur personnalisé.

Journaux à lire

Journal (log_type) Contenu Quand le lire
job-message Messages du service : autoscaling, démarrage et arrêt des workers, erreurs remontées des workers En premier : c'est le résumé du job
worker Journaux du code utilisateur et du SDK sur les workers Exceptions, Operation ongoing, erreurs de sink
worker-startup Téléchargement des paquets, démarrage des conteneurs Workers qui ne démarrent pas
harness Runner harness du Portable Runner (appelé Runner v2 dans une partie de la documentation) Pipelines multilangages, Python
shuffler Brassage exécuté sur les workers Jobs sans Streaming Engine ni Dataflow Shuffle
system, docker, kubelet Système des VM, conteneurs Arrêts brutaux, OOM tués par le noyau

Les journaux des workers sont limités à 15 000 messages par worker toutes les 30 secondes : journaliser chaque élément fait perdre les messages utiles. Un filtre d'exclusion sur resource.type="dataflow_step" dans le routeur de journaux (Cloud Logging) fait disparaître tous les journaux du job.

Cloud Profiler et Insights

  • Cloud Profiler : --dataflow_service_options=enable_google_cloud_profiler au lancement (profil CPU en Python, CPU et tas en Java et Go ; enable_google_cloud_heap_sampling en plus pour le tas en Java). Surcoût inférieur à 1 %. Le compte des workers a besoin de roles/cloudprofiler.agent ; dans Profiler, le service est le nom du job et la version son ID. Pour un modèle, passer ces options en additional experiments.
  • Dataflow Insights : les recommandations de l'onglet du même nom, exposées par l'API Recommender (gcloud recommender insights list --insight-type=google.dataflow.diagnostics.Insight --project=PROJECT_ID --location=REGION). Elles se consultent aussi depuis la carte Dataflow Diagnostics des recommandations d'Active Assist.
  • Alertes clés en main (turnkey alerts) : jeu de règles préconfigurées pour les jobs en flux (temps de résorption du backlog, croissance des vCPU), activé au lancement du job ; les règles vivent ensuite dans Cloud Monitoring (voir Alertes et incidents).

Pièges

  • Chercher la lenteur à l'étape qui déborde. Le backlog remonte vers l'amont : la source affiche le retard, l'étape fautive est en aval. Suivre le détecteur de goulots et la latence système par étape.
  • Relever max_num_workers sur une clé chaude. Les workers ajoutés restent inactifs : une clé se traite sur un seul thread.
  • Confondre rateLimitExceeded et quotaExceeded sur BigQuery. Le premier est une limite à court terme que Dataflow relance seul ; le second borne un volume et ralentit le pipeline tant qu'on ne change pas de méthode d'écriture ou de quota.
  • Purger le bucket temporaire. Une règle de cycle de vie qui supprime les fichiers de staging d'un job long empêche la création de nouveaux workers, des jours après le lancement.
  • Déboguer en journalisant chaque élément. Au-delà de la limite de débit des journaux, les messages sont perdus ; l'échantillonnage des données montre les éléments réels sans ce coût.

Alternatives en logiciel libre

  • Apache Flink (Apache 2.0) : son interface web montre la contre-pression (backpressure) par opérateur, les points de reprise et les métriques de filigrane, l'équivalent du graphe de job et du détecteur de goulots de Dataflow.
  • Apache Spark (Apache 2.0) : l'interface Spark (étapes, tâches, skew des partitions, temps de GC) et le serveur d'historique pour diagnostiquer les tâches traînardes des jobs par lots.
  • Burrow (Apache 2.0) : suivi du retard des consommateurs Kafka, évalué par partition sur une fenêtre glissante ; le pendant du backlog d'une source Pub/Sub.
  • Prometheus (Apache 2.0) avec Grafana (AGPL v3) : collecte des métriques des workers et des sources, tableaux de bord et alertes sur la fraîcheur ou le retard, ce que fournissent ici les métriques de job et Cloud Monitoring.
  • Grafana Pyroscope (AGPL v3) : profilage continu des workers, pour trouver le DoFn qui consomme le CPU comme Cloud Profiler.
  • async-profiler (Apache 2.0) : profilage à la demande d'un worker Java, sans biais des points de sécurité, quand on accède à la JVM.