Risolvere i problemi relativi ai modelli flessibili

Questa pagina fornisce suggerimenti per la risoluzione dei problemi e strategie di debug che potrebbero esserti utili se utilizzi i modelli flessibili di Dataflow. Per impostazione predefinita, il processo di avvio del modello flessibile ha un timeout di 12 minuti. Questo processo di avvio include l'estrazione dell'immagine container del modello e l'esecuzione del codice per creare il grafico del job. Se l'avvio non viene completato entro questa finestra di 12 minuti, il job non va a buon fine e viene visualizzato l'errore "Timeout in polling result file". Queste informazioni possono aiutarti a rilevare un timeout di polling, a determinarne il motivo e a correggere il problema.

Errori di timeout di polling

Il job potrebbe restituire uno dei seguenti messaggi di errore:

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

Questo errore può verificarsi per i seguenti motivi:

1. L'immagine Docker di base è stata sostituita.
2. Il account di servizio che compila SERVICE_ACCOUNT non dispone di alcune autorizzazioni necessarie.
3. Gli indirizzi IP esterni sono disabilitati e le VM non possono connettersi all'insieme di indirizzi IP esterni utilizzati dalle API di Google e dai servizi.
4. La VM di avvio non può risolvere o accedere a gcr.io.
5. Immagine container del modello flessibile di grandi dimensioni.
6. Il programma che crea il grafico impiega troppo tempo per essere completato.
7. Il codice in esecuzione nella VM di avvio impiega troppo tempo per essere completato.
8. Errori di rete o di Cloud Storage intermittenti.
9. Le opzioni della pipeline vengono sovrascritte.
10. Utenti Python: l'installazione o l'organizzazione temporanea delle dipendenze richiede troppo tempo.
11. Si è verificato un errore temporaneo.

Per risolvere il problema, controlla innanzitutto se sono presenti errori temporanei esaminando i log dei job e riprovando.

Segui le indicazioni nella sezione Problemi di avvio anticipato per attivare il logging della porta seriale, che potrebbe rivelare informazioni aggiuntive.

Se questi passaggi non risolvono il problema, prova a svolgere le seguenti operazioni di risoluzione dei problemi.

(Facoltativo) Esegui i modelli per diagnosticare ulteriormente il problema

Per identificare ulteriormente quale dei motivi precedenti potrebbe causare questo errore, utilizza le seguenti strategie:

1. Esegui il WordCount modello fornito da Google. Assicurati di fornire parametri univoci per il tuo caso d'uso, come la subnet di un progetto VPC condiviso, l'IP privato per le VM worker e il account di servizio worker di Dataflow che vuoi utilizzare. Per ulteriori informazioni su come fornire questi parametri, consulta la documentazione di riferimento di gcloud e l'API.

   Se riesci a completare il job, significa che Networking, le autorizzazioni IAM e l'accesso privato Google sono probabilmente configurati correttamente.

2. Completa la guida rapida Eseguire una pipeline utilizzando il generatore di job , che esegue il job come modello flessibile. Se il job non va a buon fine prima dell'avvio della VM worker, accedi alla VM di avvio e prova a scaricare un'immagine Docker di esempio utilizzando un comando simile al seguente:

   docker run --entrypoint /bin/bash -it gcr.io/dataflow-templates/2025-03-11-00_rc02/yaml-template
   

   Se questo comando non va a buon fine, potrebbe esserci un problema di rete con il download delle immagini. In questo caso, collabora con il tuo team di rete interno.

3. Esegui un modello flessibile fornito da Google Template e controlla il risultato. Se il job del modello fornito da Google viene completato correttamente, significa che il problema è probabilmente correlato ai file di codice del modello personalizzato specifico. In questo caso, devi continuare a risolvere i problemi del codice specifico per risolvere il problema.

Verifica il punto di ingresso di Docker

Prova questo passaggio se esegui un modello da un'immagine Docker personalizzata anziché utilizzare uno dei modelli forniti.

Controlla il punto di ingresso del container utilizzando il seguente comando:

docker inspect $TEMPLATE_IMAGE

È previsto il seguente output:

Java

/opt/google/dataflow/java_template_launcher

Python

/opt/google/dataflow/python_template_launcher

Se viene visualizzato un output diverso, il punto di ingresso del container Docker viene sostituito. Ripristina $TEMPLATE_IMAGE al valore predefinito.

Controlla le autorizzazioni del account di servizio

Verifica che il account di servizio menzionato nel messaggio disponga delle seguenti autorizzazioni:

• Deve essere in grado di leggere e scrivere il percorso Cloud Storage che compila ${file_path} nel messaggio.
• Deve essere in grado di leggere l'immagine Docker che compila ${image_url} nel messaggio.

Configura l'accesso privato Google

Se gli indirizzi IP esterni sono disabilitati, devi consentire alle VM Compute Engine di connettersi all'insieme di indirizzi IP esterni utilizzati da API di Google e servizi Google. Abilita l'accesso privato Google sulla subnet utilizzata dall'interfaccia di rete della VM.

Per i dettagli sulla configurazione, consulta Configurazione dell'accesso privato Google.

Per impostazione predefinita, quando una VM Compute Engine non ha un indirizzo IP esterno assegnato alla sua interfaccia di rete, può inviare pacchetti solo ad altre destinazioni con indirizzi IP interni.

Problemi di accesso a gcr.io

Le VM di avvio dei modelli flessibili richiedono l'accesso a gcr.io per estrarre un container dell'agente di logging (gcr.io/dataflow-templates-base/template-launcher-logger-distroless). Questo agente è responsabile dello streaming dei log di avvio in Cloud Logging. Se la VM di avvio non riesce a risolvere o connettersi a gcr.io, il processo di avvio potrebbe smettere di rispondere, causando un timeout di polling.

Questo problema può verificarsi anche se l'immagine del modello personalizzato è archiviata in Artifact Registry, perché l'agente di logging viene sempre estratto da gcr.io.

Per diagnosticare e risolvere il problema:

1. Abilita il logging della porta seriale: segui i passaggi nella sezione Problemi di avvio anticipato. Se vedi che il processo cloud-init è bloccato o se sono presenti errori relativi a gcr-wait-online.service, è probabile che si tratti di un problema di DNS o di rete.

2. Connettiti alla VM di avvio tramite SSH: utilizza il comando gcloud compute ssh per connetterti alla VM di avvio mentre è ancora in esecuzione:

   gcloud compute ssh launcher-JOB_ID --tunnel-through-iap
   

   Sostituisci JOB_ID con l'ID del job Dataflow.

3. Verifica la risoluzione DNS: esegui i seguenti comandi all'interno della VM di avvio:

   curl -I https://gcr.io
   

   Se il comando non va a buon fine e viene visualizzato l'errore "Could not resolve host", significa che nella configurazione DNS manca una voce per gcr.io.

4. Controlla se i servizi di avvio sono bloccati: esamina il log di output cloud-init:

   sudo cat /var/log/cloud-init-output.log
   

   Cerca i messaggi che indicano che il processo è in attesa della rete o che gcr.io diventi accessibile.

Inoltre, assicurati che le impostazioni DNS del VPC consentano la risoluzione di gcr.io. In alcune configurazioni di rete privata, potrebbe essere necessario aggiungere un record ADNS gcr.iospecifico per che rimandi agli intervalli IP delle API di Google limitate o delle API di Google private.

Immagine container di grandi dimensioni

Se l'immagine container del modello flessibile è di grandi dimensioni, l'estrazione e l'avvio del modello potrebbero superare il timeout predefinito di 12 minuti, causando il mancato completamento del job.

Per risolvere il problema, prova le seguenti strategie :

• Ottimizza l'immagine per ridurne le dimensioni e velocizzare il processo di estrazione.
• Utilizza il flag --launcher-machine-type per selezionare un tipo di macchina con più core CPU, in modo da estrarre l'immagine più velocemente e avviare più rapidamente.
• Utilizza il flag --launcher-vm-timeout-secs per specificare una durata di timeout più lunga per la VM di avvio, in modo che possa superare il limite predefinito di 12 minuti.

Controlla se il programma di avvio non riesce a uscire

Il programma che crea la pipeline deve essere completato prima che la pipeline possa essere avviata. L'errore di polling potrebbe indicare che l'operazione ha richiesto troppo tempo.

Ecco alcune operazioni che puoi eseguire per individuare la causa nel codice:

• Assicurati che nessun thread impedisca l'uscita dal programma. Alcuni client potrebbero creare thread propri e, se questi client non vengono arrestati, il programma attende indefinitamente che questi thread vengano uniti.
• Nel codice che definisce la pipeline, non utilizzare waitUntilFinish (per Java) o wait_until_finish (per Python). Queste funzioni impediscono l'uscita dal programma, impedendo al modello flessibile di avviare la pipeline.

Le pipeline avviate direttamente che non utilizzano un modello non presentano queste limitazioni. Pertanto, se la pipeline ha funzionato direttamente ma non come modello, l'utilizzo di un modello potrebbe essere la causa principale. Individuare il problema nel modello e correggerlo potrebbe risolverlo.

Codice a lunga esecuzione nella VM di avvio

Se il codice nel programma principale impiega troppo tempo per essere eseguito, il modello flessibile potrebbe andare in timeout prima dell'avvio della pipeline. Questo può accadere se il codice esegue calcoli complessi o effettua chiamate sincrone a risorse esterne durante l'inizializzazione.

Per diagnosticare il problema, controlla i log dei job per verificare se sono presenti operazioni che richiedono molto tempo per essere completate. Esempi includono richieste di risorse esterne, ricerche di dati di grandi dimensioni o logica di inizializzazione pesante che puoi spostare nella fase di esecuzione della pipeline.

Errori di rete o di Cloud Storage intermittenti

Gli errori intermittenti "Timeout in polling result file" o "Failed to read the result file" possono verificarsi a causa di una latenza di rete elevata o di problemi temporanei con l'API Cloud Storage. La contesa di rete cronica nel VPC, in particolare all'interno del percorso di accesso privato Google, spesso causa latenze di 400-500 ms.

Un errore "Timeout in polling result file" è in genere un errore lento, mentre un errore "Failed to read the result file" è un errore rapido, ma entrambi spesso indicano lo stesso problema di connettività sottostante.

Per diagnosticare questi errori intermittenti:

1. Controlla la latenza di rete: monitora la latenza di rete all'interno del VPC. Una latenza elevata e prolungata può causare timeout quando la VM di avvio tenta di scrivere o leggere il file dei risultati del job da Cloud Storage.

2. Monitora le metriche dell'API Cloud Storage:

   1. Nella Google Cloud console, vai alla dashboard API e servizi.

      Vai ad API e servizi abilitati

   2. Filtra e seleziona l'API Storage di Cloud.

   3. Esamina i grafici relativi a Traffico (byte inviati e ricevuti) e Frequenza di errori.

   4. Cerca i picchi di errori 5xx (ad esempio errori 503) che corrispondono all'ora esatta degli errori dei job.

Se identifichi picchi di errori o latenza elevata, esamina le prestazioni di rete del VPC o contatta l'assistenza clienti Cloud per ricevere assistenza in caso di potenziali interruzioni del servizio.

Verifica se le opzioni della pipeline richieste sono soppresse

Quando utilizzi i modelli flessibili, puoi configurare alcune, ma non tutte, le opzioni della pipeline durante l'inizializzazione della pipeline. Per ulteriori informazioni, consulta la sezione Impossibile leggere il file del job in questo documento.

Utenti Python: gestione delle dipendenze

Se esegui un job del modello flessibile Python che fornisce dipendenze aggiuntive in un file requirements.txt, il job potrebbe non essere avviato. Questo errore si verifica quando il download o l'installazione delle dipendenze specificate nel file dei requisiti richiede più tempo di quello allocato per l'avvio del modello flessibile.

Per ottimizzare le prestazioni del job, pre-pacchettizza le dipendenze durante la creazione del modello per evitare di doverle scaricare o installare durante l'avvio del modello. Per ulteriori informazioni, consulta la sezione Pacchettizzare le dipendenze per Python in "Configurare i modelli flessibili".

Errori di avvio del job

La sezione seguente contiene gli errori comuni che causano errori di avvio del job e i passaggi per risolverli o risolverli.

Problemi di avvio anticipato

Quando il processo di avvio del modello non va a buon fine in una fase iniziale, i log regolari del modello flessibile potrebbero non essere disponibili. Per esaminare i problemi di avvio, attiva il logging della porta seriale per la VM di avvio dei modelli.

Per attivare il logging per i modelli Java, imposta l'opzione enableLauncherVmSerialPortLogging su true. Per attivare il logging per i modelli Python e Go, imposta l'opzione enable_launcher_vm_serial_port_logging su true. Nella Google Cloud console, il parametro è elencato in Parametri facoltativi come Abilita il logging della porta seriale della VM di avvio.

Puoi visualizzare i log di output della porta seriale della VM di avvio dei modelli in Cloud Logging. Per trovare i log di una determinata VM di avvio, utilizza la query resource.type="gce_instance" "launcher-number" dove number inizia con la data corrente nel formato YYYMMDD.

I criteri dell'organizzazione potrebbero impedirti di attivare il logging degli output della porta seriale.

Impossibile leggere il file del job

Quando provi a eseguire un job da un modello flessibile, il job potrebbe non andare a buon fine e viene visualizzato il seguente errore:

Failed to read the job file : gs://dataflow-staging-REGION-PROJECT_ID/staging/template_launches/TIMESTAMP/job_object...

Questo errore si verifica quando le opzioni di inizializzazione della pipeline necessarie vengono sovrascritte. Quando utilizzi i modelli flessibili, puoi configurare alcune, ma non tutte, le opzioni della pipeline durante l'inizializzazione della pipeline. Se gli argomenti della riga di comando richiesti dal modello flessibile vengono sovrascritti, il job potrebbe ignorare, sostituire o eliminare le opzioni della pipeline passate dal programma di avvio del modello. Il job potrebbe non essere avviato oppure potrebbe essere avviato un job che non utilizza il modello flessibile.

Per evitare questo problema, durante l'inizializzazione della pipeline, non modificare le seguenti opzioni della pipeline nel codice utente o nel file metadata.json:

Java

• runner
• project
• jobName
• templateLocation
• region

Python

• runner
• project
• job_name
• template_location
• region

Go

• runner
• project
• job_name
• template_location
• region

Impossibile leggere il file dei risultati

Quando provi a eseguire un job da un modello flessibile, il job potrebbe non andare a buon fine e viene visualizzato il seguente errore:

Failed to read the result file : gs://BUCKET_NAME...

Questo errore si verifica quando il service account predefinito di Compute Engine non dispone di tutte le autorizzazioni necessarie per eseguire un modello flessibile.

Per l'elenco delle autorizzazioni richieste, consulta Autorizzazioni per eseguire un modello flessibile.

Questo errore può anche essere causato da problemi intermittenti di latenza di rete o dell'API Storage di Cloud Storage. Per ulteriori informazioni, consulta Errori di rete o di Cloud Storage intermittenti.

Autorizzazione negata per la risorsa

Quando provi a eseguire un job da un modello flessibile, il job potrebbe non andare a buon fine e viene visualizzato il seguente errore:

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

Questo errore si verifica quando il account di servizio utilizzato non dispone delle autorizzazioni per accedere alle risorse necessarie per eseguire un modello flessibile.

Per evitare questo problema, verifica che il account di servizio disponga delle autorizzazioni richieste. Modifica le autorizzazioni del account di servizio in base alle esigenze.

Flag fornito ma non definito

Quando provi a eseguire un modello flessibile Go con l'opzione della pipeline worker_machine_type, la pipeline non va a buon fine e viene visualizzato il seguente errore:

flag provided but not defined: -machine_type

Questo errore è causato da un problema noto nelle versioni 2.47.0 e precedenti dell'SDK Apache Beam Go. Per risolvere il problema, esegui l'upgrade ad Apache Beam Go versione 2.48.0 o successive.

Impossibile recuperare il JAR del server job remoto

Se provi a eseguire un job da un modello flessibile quando non sei connesso a internet, il job potrebbe non andare a buon fine e viene visualizzato il seguente errore:

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

Questo errore si verifica perché la VM non è in grado di scaricare il pacchetto Java di Apache Beam da internet. Questo pacchetto è obbligatorio quando esegui un job multilingue utilizzando un modello flessibile.

Per risolvere il problema, apporta una delle seguenti modifiche:

• Connettiti a internet. Quando sei connesso a internet, il job può accedere al file richiesto.

• Includi il pacchetto Java di Apache Beam nella directory locale in modo che il job possa accedervi localmente. Inserisci il file nella seguente directory: /root/.apache_beam/cache/jars/. Ad esempio, /root/.apache_beam/cache/jars/beam-sdks-java-io-expansion-service-SDK_VERSION.jar.

Impossibile ottenere il file system dal percorso specificato

Quando provi a eseguire un job da un modello flessibile, il job potrebbe non andare a buon fine e viene visualizzato il seguente errore:

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

Questo errore si verifica quando il job utilizza un'immagine container del modello flessibile e l'immagine container non contiene un'installazione Java.

Per risolvere il problema, aggiungi la seguente riga al Dockerfile:

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

Questo comando installa Java nell'ambiente container.

Esaurimento delle risorse della VM di avvio

Quando provi a eseguire un job da un modello flessibile, il job potrebbe non andare a buon fine e viene visualizzato il seguente errore:

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.

Il nome della VM launcher-ID rappresenta il nome della VM di avvio. La VM di avvio è responsabile della raccolta delle risorse del job, come il codice e l'immagine del modello, prima di creare e inviare il grafico del job al servizio Dataflow per avviare il lavoro.

Se non specifichi il parametro launcherMachineType, Dataflow sceglie un tipo di macchina predefinito per la VM di avvio. Questa scelta è indipendente da machineType del worker. Gli errori di esaurimento delle risorse possono verificarsi se questo tipo di macchina predefinito non è disponibile nella regione o nella zona del job.

Per risolvere il problema, utilizza una delle seguenti strategie:

• Aggiorna il tipo di macchina di avvio a un tipo di macchina diverso machine type e riprova a eseguire il job.
  • API REST: imposta launchParameter.environment.launcherMachineType nel metodo flexTemplates.launch.
  • gcloud CLI: imposta il --launcher-machine-type flag nel gcloud dataflow flex-template run comando.
• Avvia il modello flessibile da un'altra regione.

Ritardo del programma di avvio del modello flessibile

Quando invii un job del modello flessibile, la richiesta del job viene inserita in una coda Spanner. Il programma di avvio del modello recupera il job dalla coda Spanner e poi esegue il modello. Quando Spanner ha un backlog di messaggi, potrebbe verificarsi un ritardo significativo tra il momento in cui invii il job e il momento in cui viene avviato.

Per risolvere il problema, avvia il modello flessibile da un'altra regione.

I parametri del modello non sono validi

Quando provi a utilizzare gcloud CLI per eseguire un job che utilizza un modello fornito da Google, si verifica il seguente errore:

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

Questo errore si verifica perché alcuni modelli forniti da Google non supportano le opzioni defaultSdkHarnessLog e defaultWorkerLog.

Per risolvere il problema, copia il file di specifica del modello in un bucket Cloud Storage. Aggiungi i seguenti parametri aggiuntivi al file.

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

Dopo aver apportato questa modifica al file del modello, utilizza il seguente comando per eseguire il modello.

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

Sostituisci i seguenti valori:

• BUCKET_NAME: il nome del bucket Cloud Storage
• FILENAME: il nome del file di specifica del modello

I log del programma di avvio del modello flessibile mostrano una gravità errata

Quando l'avvio di un modello flessibile personalizzato non va a buon fine, nei file di log viene visualizzato il seguente messaggio con gravità ERROR:

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

La causa principale dell'errore di avvio viene in genere visualizzata nei log prima di questo messaggio con gravità INFO. Sebbene questo livello di log possa essere errato, è previsto, perché il programma di avvio del modello flessibile non ha modo di estrarre i dettagli di gravità dai messaggi di log generati dall'applicazione Apache Beam.

Se vuoi visualizzare la gravità corretta per ogni messaggio nel log del programma di avvio, configura il modello in modo che generi log in formato JSON anziché in testo normale. Questa configurazione consente al programma di avvio del modello di estrarre la gravità corretta del messaggio di log. Utilizza la seguente struttura del messaggio:

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

In Java, puoi utilizzare il logger Logback con un'implementazione personalizzata dell'appender JSON. Per ulteriori informazioni, consulta la configurazione di esempio di Logback e il codice di esempio dell'appender JSON in GitHub.

Questo problema riguarda solo i log generati dal programma di avvio del modello flessibile durante l'avvio della pipeline. Quando l'avvio va a buon fine e la pipeline è in esecuzione, i log generati dai worker di Dataflow hanno la gravità corretta.

I modelli forniti da Google mostrano la gravità corretta durante l'avvio del job, perché i modelli forniti da Google utilizzano questo approccio di logging JSON.