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.

Risolvere i problemi relativi ai timeout del polling

Questa sezione fornisce 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. Il 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 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, controlla innanzitutto la presenza di errori temporanei esaminando i log dei job e riprovando. Se questi passaggi non risolvono il problema, prova a svolgere le seguenti operazioni di risoluzione dei problemi.

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:

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 disabilitati, 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 Configurare l'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 di indirizzi IP interni.

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 maggiori informazioni, vedi la sezione Impossibile leggere il file del job in questo documento.

Rimuovi Apache Beam dal file requirements (solo Python)

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.

Timeout del polling quando si utilizza Python

Se esegui un job Dataflow utilizzando un modello flessibile e Python, il job potrebbe essere messo in coda per un periodo di tempo, non essere eseguito e quindi 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 esaminare 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 VM di avvio specifica, 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 riuscire e restituire 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 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:

Impossibile leggere il file dei risultati

Quando provi a eseguire un job da un modello flessibile, il job potrebbe non riuscire e restituire 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 flessibile. 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 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 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 è necessario 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 ottenere il file system dal percorso specificato

Quando provi a 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 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 di 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é utilizzano questo approccio di logging JSON.