Risolvere i problemi relativi a Modelli flessibili

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

Risolvere i problemi relativi ai timeout del polling

Questa sezione illustra i passaggi per identificare la causa dei timeout di polling.

Timeout del polling

Il job del modello flessibile potrebbe restituire il seguente messaggio di errore:

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

Questo errore può verificarsi per i seguenti motivi:

  1. L'immagine Docker di base è stata sostituita.
  2. L'account di servizio che compila ${service_account_email} 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 e dai servizi Google.
  4. Il programma che crea il grafico impiega troppo tempo per essere completato.
  5. Le opzioni della pipeline vengono sovrascritte.
  6. (Solo Python) Si è verificato un problema con il file requirements.txt.
  7. Si è verificato un errore temporaneo.

Per risolvere il problema, verifica innanzitutto la presenza di errori temporanei controllando i log del job e riprova. Se questi passaggi non risolvono il problema, prova a svolgere i passaggi per la risoluzione dei problemi che seguono.

Verifica il punto di contatto Docker

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

Controlla il punto di contatto del contenitore 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, l'entrypoint del contenitore Docker è stato soprascritto. Ripristina $TEMPLATE_IMAGE al valore predefinito.

Controllare le autorizzazioni dell'account di servizio

Verifica che l'account di servizio menzionato nel messaggio abbia le seguenti autorizzazioni:

  • Deve essere in grado di leggere e scrivere il percorso di Cloud Storage che viene inserito ${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 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 sulla configurazione, consulta Configurare l'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 di indirizzi IP interni.

Controlla se il programma di avvio non riesce a uscire

Il programma che costruisce 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.

Di seguito sono riportate alcune azioni che puoi eseguire per individuare la causa nel codice:

  • Controlla i log dei job per verificare se l'esecuzione di un'operazione richiede molto tempo. Un esempio è una richiesta di una risorsa esterna.
  • Assicurati che nessun thread stia bloccando l'uscita del programma. Alcuni client potrebbero creare i propri thread e, se non vengono arrestati, il programma attende indefinitamente che questi thread vengano uniti.

Le pipeline lanciate direttamente e 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 risolvere il problema.

Verificare se le opzioni di pipeline richieste sono eliminate

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

Rimuovi Apache Beam dal file dei requisiti (solo Python)

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

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

Inserire Apache Beam nel file dei requisiti può causare tempi di lancio lunghi, spesso con conseguente timeout.

Timeout di polling quando si utilizza Python

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

Timeout in polling

L'errore è causato dal file requirements.txt utilizzato per installare le dipendenze richieste. Quando avvii un job Dataflow, tutte le dipendenze vengono prima messe in fase per rendere questi file accessibili alle VM worker. Questa procedura 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 del tempo. PyArrow è una dipendenza indiretta utilizzata da Apache Beam e dalla maggior parte delle librerie client di Cloud.

Per ottimizzare il rendimento del job, utilizza un Dockerfile o un container personalizzato per precompilare le dipendenze. Per ulteriori informazioni, consulta Dipendenze dei pacchetti in "Configurare i modelli flessibili".

Errori di avvio del job

La sezione seguente contiene gli errori comuni che causano i fallimenti del lancio dei job e i passaggi per risolverli o per la risoluzione dei problemi.

Problemi di avvio iniziale

Quando la procedura di lancio del modello non va a buon fine in una fase iniziale, i log regolari di Flex Template potrebbero non essere disponibili. Per esaminare i problemi di avvio, abilita 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 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 il logging della porta seriale della VM del programma di lancio.

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

I criteri dell'organizzazione potrebbero impedirti di attivare il logging delle uscite della porta seriale.

Impossibile leggere il file del job

Quando provi a eseguire un job da un modello flessibile, il job potrebbe non riuscire con il seguente errore:

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

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 ignorare le opzioni della pipeline trasmesse dal programma di lancio del modello. L'avvio del job potrebbe non riuscire 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 provi a eseguire un job da un modello flessibile, il job potrebbe non riuscire con il seguente errore:

Failed to read the result file : gs://BUCKET_NAME with error message: (ERROR_NUMBER): Unable to open template 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 Flex. Per l'elenco delle autorizzazioni richieste, consulta Autorizzazioni per eseguire un modello flessibile.

Autorizzazione negata per la risorsa

Quando provi a eseguire un job da un modello flessibile, il job potrebbe non riuscire con 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 l'account di servizio utilizzato non dispone delle autorizzazioni per accedere alle risorse necessarie per eseguire un modello flessibile.

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

Flag fornito ma non definito

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

flag provided but not defined: -machine_type

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

Impossibile recuperare il file jar del server di job remoto

Se provi a eseguire un job da un modello Flex quando non sei connesso a internet, il job potrebbe non riuscire con 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 è necessario quando esegui un job in più lingue 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 di Apache Beam nella tua 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 provi a eseguire un job da un modello flessibile, il job potrebbe non riuscire con 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 di Flex Template 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 del contenitore.

Ritardo dell'avvio del modello flessibile

Quando invii un job di modello flessibile, la richiesta 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 una regione diversa.

I parametri del modello non sono validi

Quando provi a utilizzare lgcloud 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 specifiche 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 lancio del modello flessibile mostrano una gravità errata

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

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

La causa principale del fallimento del lancio viene solitamente visualizzata nei log precedenti a questo messaggio con la gravità INFO. Sebbene questo livello di log possa essere errato, è previsto, in quanto il programma di avvio del modello flessibile non ha modo di estrarre i dettagli sulla gravità dai messaggi di log prodotti dall'applicazione Apache Beam.

Se vuoi visualizzare la gravità corretta per ogni messaggio nel log del programma di avvio, configura il modello in modo da generare i log in formato JSON anziché in testo normale. Questa configurazione consente al programma di avvio del modello di estrarre la gravità corretta del messaggio 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 di appender JSON personalizzato. Per ulteriori informazioni, consulta la configurazione di esempio di Logback e il codice di esempio dell'appender JSON su GitHub.

Questo problema riguarda solo i log generati dal programma di lancio dei modelli flessibili durante l'avvio della pipeline. Quando il lancio è andato 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 il lancio del job, perché i modelli forniti da Google utilizzano questo approccio di registrazione JSON.