Fehlerbehebung bei Flex-Vorlagen

Auf dieser Seite finden Sie Tipps und Strategien zur Fehlerbehebung, die nützlich sein könnten, wenn Sie flexible Dataflow-Vorlagen verwenden. Anhand dieser Informationen können Sie ein Zeitlimit für die Abfrage ermitteln, den Grund für das Zeitlimit ermitteln und das Problem beheben.

Fehlerbehebung bei Zeitüberschreitungen bei Abfragen

In diesem Abschnitt wird beschrieben, wie Sie die Ursache von Zeitüberschreitungen beim Polling ermitteln können.

Zeitüberschreitungen beim Polling

Ihr flexibler Vorlagenjob gibt möglicherweise die folgende Fehlermeldung zurück:

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

Dieser Fehler kann folgende Ursachen haben:

  1. Das Basis-Docker-Image wurde überschrieben.
  2. Das Dienstkonto, mit dem ${service_account_email} gefüllt wird, hat nicht alle erforderlichen Berechtigungen.
  3. Externe IP-Adressen sind deaktiviert und VMs können keine Verbindung zu der Gruppe von externen IP-Adressen herstellen, die von Google APIs und Diensten verwendet werden.
  4. Das Programm, das die Grafik erstellt, braucht zu lange.
  5. Pipelineoptionen werden überschrieben.
  6. (Nur Python) Es gibt ein Problem mit der requirements.txt-Datei.
  7. Ein vorübergehender Fehler ist aufgetreten.

Prüfen Sie zur Behebung dieses Problems zuerst die Joblogs auf Fehler und versuchen Sie es noch einmal. Wenn das Problem durch diese Schritte nicht behoben wird, führen Sie die folgenden Schritte zur Fehlerbehebung aus.

Docker-Einstiegspunkt prüfen

Führen Sie diesen Schritt aus, wenn Sie eine Vorlage aus einem benutzerdefinierten Docker-Image ausführen, anstatt eine der bereitgestellten Vorlagen zu verwenden.

Suchen Sie mit dem folgenden Befehl nach dem Containereinstiegspunkt:

docker inspect $TEMPLATE_IMAGE

Die folgende Ausgabe wird erwartet:

Java

/opt/google/dataflow/java_template_launcher

Python

/opt/google/dataflow/python_template_launcher

Wenn Sie eine andere Ausgabe erhalten, wird der Einstiegspunkt Ihres Docker-Containers überschrieben. Stellen Sie $TEMPLATE_IMAGE wieder auf die Standardeinstellung her.

Dienstkontoberechtigungen prüfen

Prüfen Sie, ob das in der Nachricht erwähnte Dienstkonto die folgenden Berechtigungen hat:

  • Es muss den Cloud Storage-Pfad lesen und schreiben können, mit dem ${file_path} in der Nachricht gefüllt wird.
  • Es muss das Docker-Image lesen können, mit dem ${image_url} in der Nachricht gefüllt wird.

Privaten Google-Zugriff konfigurieren

Wenn externe IP-Adressen deaktiviert sind, müssen Sie Compute Engine-VMs erlauben, eine Verbindung zu der Gruppe von externen IP-Adressen herzustellen, die von Google APIs und Diensten verwendet werden. Aktivieren Sie den privaten Google-Zugriff in dem Subnetz, das von der Netzwerkschnittstelle der VM verwendet wird.

Weitere Konfigurationsdetails finden Sie unter Privaten Google-Zugriff konfigurieren.

Wenn einer Compute Engine-VM eine externe IP-Adresse fehlt, die der Netzwerkschnittstelle zugewiesen ist, kann sie standardmäßig nur Pakete an andere interne IP-Adressen senden.

Prüfen, ob das Launcher-Programm nicht beendet werden kann

Das Programm, das die Pipeline erstellt, muss abgeschlossen sein, bevor die Pipeline gestartet werden kann. Der Abfragefehler könnte darauf hinweisen, dass es zu lange gedauert hat.

Sie können die Ursache im Code beispielsweise so ermitteln:

  • Prüfen Sie in den Joblogs, ob die Ausführung eines Vorgangs sehr lange dauert. Ein Beispiel wäre eine Anfrage für eine externe Ressource.
  • Achten Sie darauf, dass das Beenden des Programms nicht von Threads blockiert wird. Einige Clients erstellen möglicherweise ihre eigenen Threads. Wenn diese Clients nicht heruntergefahren werden, wartet das Programm für immer, bis diese Threads verbunden werden.

Pipelines, die direkt gestartet werden und keine Vorlage verwenden, haben diese Einschränkungen nicht. Wenn die Pipeline also direkt (nicht als Vorlage) funktionierte, könnte die Verwendung einer Vorlage die Ursache sein. Wenn Sie das Problem in der Vorlage finden und die Vorlage beheben, kann das Problem möglicherweise behoben werden.

Prüfen, ob erforderliche Pipelineoptionen unterdrückt werden

Bei Verwendung von Flex-Vorlagen können Sie einige, aber nicht alle Pipelineoptionen bei der Pipelineinitialisierung konfigurieren. Weitere Informationen finden Sie im Abschnitt Jobdatei konnte nicht gelesen werden in diesem Dokument.

Apache Beam aus der Anforderungsdatei entfernen (nur Python)

Wenn Ihr Dockerfile eine requirements.txt mit apache-beam[gcp] enthält, entfernen Sie sie aus der Datei und installieren sie separat. Mit dem folgenden Befehl wird dieser Schritt veranschaulicht:

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

Das Festlegen von Apache Beam in der Anforderungsdatei kann zu langen Startzeiten führen, die häufig Zeitüberschreitungen bedingen.

Zeitüberschreitungen bei Verwendung von Python

Wenn Sie einen Dataflow-Job mithilfe einer Flex Template und Python ausführen, wird der Job möglicherweise für einen bestimmten Zeitraum in die Warteschlange gestellt und nicht ausgeführt. Er zeigt dann den folgenden Fehler an:

Timeout in polling

Die requirements.txt-Datei, die zum Installieren der erforderlichen Abhängigkeiten verwendet wird, verursacht den Fehler. Wenn Sie einen Dataflow-Job starten, werden zuerst alle Abhängigkeiten bereitgestellt, damit die Dateien für die Worker-VMs zugänglich sind. Bei diesem Vorgang wird jede direkte und indirekte Abhängigkeit in die Datei requirements.txt heruntergeladen und kompiliert. Die Kompilierung einiger Abhängigkeiten kann einige Minuten dauern. Insbesondere die Kompilierung von PyArrow kann etwas Zeit in Anspruch nehmen. PyArrow ist eine indirekte Abhängigkeit, die von Apache Beam und den meisten Cloud-Clientbibliotheken verwendet wird.

Optimieren Sie die Leistung Ihres Jobs, indem Sie die Abhängigkeiten mit einem Dockerfile oder einem benutzerdefinierten Container verpacken. Weitere Informationen finden Sie unter Paketabhängigkeiten unter „Flexible Vorlagen konfigurieren“.

Fehler beim Starten von Jobs

Der folgende Abschnitt enthält häufige Fehler beim Starten von Jobs sowie Schritte zur Behebung dieser Fehler.

Probleme beim frühen Start

Wenn der Start der Vorlage in einem frühen Stadium fehlschlägt, sind möglicherweise keine regulären Flex-Vorlagenlogs verfügbar. Zum Untersuchen von Startproblemen aktivieren Sie das Logging für den seriellen Port für die Vorlagen-Launcher-VM.

Legen Sie für die Option enableLauncherVmSerialPortLogging den Wert true fest, um das Logging für Java-Vorlagen zu aktivieren. Zum Aktivieren des Loggings für Python- und Go-Vorlagen legen Sie für die Option enable_launcher_vm_serial_port_logging den Wert true fest. In der Google Cloud Console wird der Parameter unter Optionale Parameter als Logging des seriellen Ports für die Launcher-VM aktivieren aufgeführt.

Sie können die Logs für die Ausgabe des seriellen Ports der Vorlagen-Launcher-VM in Cloud Logging ansehen. Verwenden Sie die Abfrage resource.type="gce_instance" "launcher-number", um die Logs für eine bestimmte Launcher-VM zu ermitteln. Dabei beginnt number mit dem aktuellen Datum im Format YYYMMDD.

Ihre Organisationsrichtlinie lässt das Logging der Ausgabe des seriellen Ports möglicherweise nicht zu.

Jobdatei konnte nicht gelesen werden

Wenn Sie versuchen, einen Job aus einer Flex-Vorlage auszuführen, schlägt der Job möglicherweise mit einem der folgenden Fehler fehl:

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

oder:

Failed to read the result file : gs://BUCKET_NAME with error message: (ERROR_NUMBER): Unable to open template file: gs://BUCKET_NAME

Dieser Fehler tritt auf, wenn die erforderlichen Optionen für die Pipelineinitialisierung überschrieben werden. Bei Verwendung von Flex-Vorlagen können Sie einige, aber nicht alle Pipelineoptionen bei der Pipelineinitialisierung konfigurieren. Wenn die von der Flex-Vorlage erforderlichen Befehlszeilenargumente überschrieben werden, kann es sein, dass der Job die vom Vorlagen-Launcher übergebenen Pipelineoptionen ignoriert, überschreibt oder verwirft. Der Job wird möglicherweise nicht gestartet, oder es wird ein Job gestartet, der die Flex-Vorlage nicht verwendet.

Ändern Sie zur Vermeidung dieses Problems während der Pipelineinitialisierung die folgenden Pipelineoptionen im Nutzercode oder in der metadata.json-Datei nicht:

Java

  • runner
  • project
  • jobName
  • templateLocation
  • region

Python

  • runner
  • project
  • job_name
  • template_location
  • region

Go

  • runner
  • project
  • job_name
  • template_location
  • region

Berechtigung für Ressource verweigert

Wenn Sie versuchen, einen Job aus einer flexiblen Vorlage auszuführen, schlägt der Job möglicherweise mit dem folgenden Fehler fehl:

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

Dieser Fehler tritt auf, wenn das verwendete Dienstkonto nicht berechtigt ist, auf erforderliche Ressourcen zum Ausführen einer Flex-Vorlage zuzugreifen.

Prüfen Sie, ob das Dienstkonto die erforderlichen Berechtigungen hat, um dieses Problem zu vermeiden. Passen Sie die Berechtigungen des Dienstkontos nach Bedarf an.

Flag angegeben, aber nicht definiert

Wenn Sie versuchen, eine Go-Flex-Vorlage mit der Pipelineoption worker_machine_type auszuführen, schlägt die Pipeline mit dem folgenden Fehler fehl:

flag provided but not defined: -machine_type

Dieser Fehler wird durch ein bekanntes Problem in den Apache Beam Go SDK-Versionen 2.47.0 und niedriger verursacht. Führen Sie zur Behebung dieses Problems ein Upgrade auf Apache Beam Go Version 2.48.0 oder höher durch.

Verzögerung beim Flex-Vorlagen-Launcher

Wenn Sie einen Job mit flexibler Vorlage senden, wird die Jobanfrage in eine Spanner-Warteschlange gestellt. Der Vorlagen-Launcher ruft den Job aus der Spanner-Warteschlange ab und führt dann die Vorlage aus. Falls Spanner einen Nachrichtenrückstand hat, kann es zwischen dem Senden und dem Start des Jobs zu einer erheblichen Verzögerung kommen.

Zur Umgehung dieses Problems starten Sie die flexible Vorlage in einer anderen Region.

Die Vorlagenparameter sind ungültig

Wenn Sie versuchen, mit der gcloud CLI einen Job auszuführen, der eine von Google bereitgestellte Vorlage verwendet, tritt der folgende Fehler auf:

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

Dieser Fehler tritt auf, weil einige von Google bereitgestellten Vorlagen die Optionen defaultSdkHarnessLog und defaultWorkerLog nicht unterstützen.

Kopieren Sie als Behelfslösung die Vorlagenspezifikationsdatei in einen Cloud Storage-Bucket. Fügen Sie der Datei die folgenden zusätzlichen Parameter hinzu.

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

Nachdem Sie diese Änderung an der Vorlagendatei vorgenommen haben, führen Sie die Vorlage mit dem folgenden Befehl aus.

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

Ersetzen Sie die folgenden Werte:

  • BUCKET_NAME: der Name Ihres Cloud Storage-Buckets
  • FILENAME: durch den Name Ihrer Vorlagenspezifikationsdatei

Flexible Vorlage-Launcher-Logs zeigen den falschen Schweregrad an

Wenn die Ausführung einer benutzerdefinierten flexiblen Vorlage fehlschlägt, wird in den Logdateien die folgende Meldung mit dem Schweregrad ERROR angezeigt:

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

Die Grundursache des Startfehlers wird in den Protokollen in der Regel vor dieser Meldung mit der Schwere INFO angezeigt. Obwohl diese Logebene möglicherweise falsch ist, ist sie zu erwarten, da mit dem Launcher für flexible Vorlagen keine Schweregraddetails aus den von der Apache Beam-Anwendung generierten Lognachrichten extrahiert werden können.

Wenn Sie den korrekten Schweregrad für jede Nachricht im Launcher-Protokoll sehen möchten, konfigurieren Sie Ihre Vorlage so, dass Protokolle im JSON-Format statt im Klartext generiert werden. Mit dieser Konfiguration kann der Vorlagen-Launcher den korrekten Schweregrad der Logeinträge extrahieren. Verwenden Sie die folgende Nachrichtenstruktur:

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

In Java können Sie den Logback-Logger mit einer benutzerdefinierten JSON-Appender-Implementierung verwenden. Weitere Informationen finden Sie in der Logback-Beispielkonfiguration und im Beispielcode für den JSON-Appender auf GitHub.

Dieses Problem wirkt sich nur auf die Protokolle aus, die vom Launcher für flexible Vorlagen beim Starten der Pipeline generiert werden. Wenn der Start erfolgreich war und die Pipeline ausgeführt wird, haben die von Dataflow-Workern erstellten Logs den korrekten Schweregrad.

Von Google bereitgestellte Vorlagen zeigen den richtigen Schweregrad während des Jobstarts, da die von Google bereitgestellten Vorlagen diesen JSON-Logging-Ansatz verwenden.