Risolvere i problemi relativi a Modelli flessibili

Questa pagina fornisce suggerimenti per la risoluzione dei problemi e strategie di debug che potrebbero esserti utili se utilizzi i modelli flessibili Dataflow. Queste informazioni possono aiutarti a rilevare un timeout del polling, a determinare il motivo del timeout e a correggere il problema.

Errori di timeout del polling

Il tuo 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 disattivati e le VM non possono connettersi all'insieme di indirizzi IP esterni utilizzati dalle API e dai servizi Google.
  4. Il programma che crea il grafico impiega troppo tempo per essere completato.
  5. Le opzioni pipeline vengono sovrascritte.
  6. Utenti Python: si è verificato un problema con il file requirements.txt.
  7. Si è verificato un errore temporaneo.

Per risolvere il problema, controlla innanzitutto la presenza di errori temporanei controllando i log dei job e riprova.

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 modello WordCount fornito da Google. Assicurati di fornire parametri univoci per il tuo caso d'uso, ad esempio la subnet di un progetto VPC condiviso, l'IP privato per le VM worker e ilaccount di serviziont worker Dataflow che vuoi utilizzare. Per ulteriori informazioni su come fornire questi parametri, consulta il riferimento gcloud e il riferimento API.

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

  2. Completa la guida rapida Esegui una pipeline utilizzando Job Builder, che esegue il job come modello flessibile. Se il job non riesce prima dell'avvio della VM worker, accedi alla VM launcher 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 networking interno.

  3. Esegui un modello Flex fornito da Google 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 relativi al tuo 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.

Verifica 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 ignorato. Ripristina $TEMPLATE_IMAGE al valore predefinito.

Controlla le autorizzazioni dell'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.

Configurazione dell'accesso privato Google

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

Per i dettagli della configurazione, vedi Configurazione dell'accesso privato Google.

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

Controllare se il programma di avvio non viene chiuso

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

Ecco alcune cose che puoi fare per individuare la causa nel codice:

  • Controlla i log dei job e verifica se il completamento di un'operazione richiede molto tempo. Un esempio è una richiesta di una risorsa esterna.
  • Assicurati che nessun thread impedisca l'uscita dal programma. Alcuni client potrebbero creare i propri thread e, se questi client non vengono chiusi, il programma attende per sempre che questi thread vengano uniti.

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.

Verifica se le opzioni della pipeline richieste sono soppresse

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

Utenti Python: rimuovi Apache Beam dal file requirements

Se il Dockerfile include requirements.txt con apache-beam[gcp], rimuovilo dal file e installalo separatamente. Il seguente comando mostra come completare questo passaggio:

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

L'inserimento di Apache Beam nel file dei requisiti può causare tempi di avvio lunghi, spesso con conseguente timeout. Per saperne di più, consulta il bug di monitoraggio di questo problema del team di Apache Arrow.

Utenti Python: pre-pacchettizza le dipendenze

Se esegui un job Dataflow utilizzando un modello flessibile e Python, il job potrebbe essere messo in coda per un periodo, non essere eseguito e poi visualizzare il seguente errore:

Timeout in polling

Il file requirements.txt utilizzato per installare le dipendenze richieste causa l'errore. Quando avvii un job Dataflow, tutte le dipendenze vengono prima sottoposte a staging per rendere questi file accessibili alle VM worker. Questo processo prevede il download e la compilazione di ogni dipendenza diretta e indiretta nel file requirements.txt. La compilazione di alcune dipendenze potrebbe richiedere diversi minuti. In particolare, la compilazione di PyArrow potrebbe richiedere tempo. PyArrow è una dipendenza indiretta utilizzata da Apache Beam e dalla maggior parte delle librerie client Cloud.

Per ottimizzare il rendimento del job, utilizza un Dockerfile o un container personalizzato per preconfezionare le dipendenze. Per saperne di più, consulta la sezione Dipendenze dei pacchetti in "Configurare i modelli flessibili".

Errori di avvio del job

La sezione seguente contiene gli errori comuni che causano errori di avvio dei job e i passaggi per risolvere o risolvere i problemi relativi agli errori.

Problemi di avvio anticipato

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

Per abilitare la registrazione per i modelli Java, imposta l'opzione enableLauncherVmSerialPortLogging su true. Per abilitare la registrazione per i modelli Python e Go, imposta l'opzione enable_launcher_vm_serial_port_logging su true. Nella console Google Cloud , il parametro è elencato in Parametri facoltativi come Abilita la registrazione 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 particolare 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 la registrazione degli output della porta seriale.

Impossibile leggere il file del job

Quando tenti di eseguire un job da un modello flessibile, il job potrebbe non riuscire e restituire 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 opzioni della pipeline, ma non tutte, 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 trasmesse dal launcher del modello. Il job potrebbe non essere avviato o 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

Vai

  • runner
  • project
  • job_name
  • template_location
  • region

Impossibile leggere il file dei risultati

Quando tenti di eseguire un job da un modello flessibile, il job potrebbe non riuscire e viene visualizzato il seguente errore:

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

Questo errore si verifica quando il service account Compute Engine predefinito 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.

Autorizzazione negata per la risorsa

Quando tenti di eseguire un job da un modello flessibile, il job potrebbe non riuscire e restituire 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 file JAR del server di job remoto

Se provi a eseguire un job da un modello flessibile quando non sei connesso a internet, il job potrebbe non riuscire e visualizzare 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 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 è connesso a internet, il tuo job può accedere al file richiesto.

  • Includi il pacchetto Java Apache Beam nella directory locale in modo che il tuo 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 recuperare il file system dal percorso specificato

Quando tenti di eseguire un job da un modello flessibile, il job potrebbe non riuscire e restituire 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.

Ritardo dell'avvio dei modelli flessibili

Quando invii un job modello flessibile, la richiesta di job viene inserita in una coda Spanner. Il launcher del modello preleva il job dalla coda di 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.

Come soluzione alternativa, 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 launcher dei modelli flessibili mostrano una gravità errata

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

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

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

Se vuoi visualizzare la gravità corretta per ogni messaggio nel log del launcher, configura il modello in modo che generi log in formato JSON anziché in formato di testo normale. Questa configurazione consente al launcher 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 Logback logger con un'implementazione personalizzata dell'appender JSON. Per maggiori informazioni, consulta la configurazione di esempio di Logback e il codice di esempio dell'aggiunta JSON su GitHub.

Questo problema riguarda solo i log generati dal launcher del modello flessibile durante l'avvio della pipeline. Quando il lancio va a buon fine e la pipeline è in esecuzione, i log prodotti dai worker 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.