Flex テンプレートのトラブルシューティング

このページでは、Dataflow Flex テンプレートを使用している場合に役立つ可能性があるトラブルシューティングのヒントとデバッグ戦略について説明します。この情報は、ポーリング タイムアウトの検出、タイムアウトの理由の特定、問題の解決に役立ちます。

ポーリング タイムアウト エラー

ジョブから次のいずれかのエラー メッセージが返されることがあります。

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

エラーの原因としては、次のことが考えられます。

  1. ベース Docker イメージがオーバーライドされた。
  2. SERVICE_ACCOUNT に入力されるサービス アカウントに必要な権限が付与されていない。
  3. 外部 IP アドレスが無効で、VM が Google API とサービスで使用される外部 IP アドレスのセットに接続できない。
  4. グラフを作成するプログラムの完了に時間がかかっている。
  5. パイプライン オプションが上書きされている。
  6. Python ユーザー: 依存関係のインストールまたはステージングに時間がかかりすぎている。
  7. 一時的なエラーが発生した。

この問題を解決するには、まずジョブログを確認して再試行し、一時的なエラーがないか確認してください。

早期起動に関する問題セクションのガイダンスに沿って、シリアルポートのロギングを有効にします。これにより、追加情報が明らかになる可能性があります。

上記の手順で問題を解決できない場合は、次のトラブルシューティング手順をお試しください。

省略可: テンプレートを実行して問題をさらに診断する

前述の理由の中から、このエラーの原因となっている可能性のあるものを特定するには、次の方法をお試しください。

  1. Google 提供の WordCount テンプレートを実行します。共有 VPC プロジェクトのサブネットワーク、ワーカー VM のプライベート IP、使用する Dataflow ワーカー サービス アカウントなど、ご自身のユースケースに固有のパラメータを指定してください。これらのパラメータの指定方法の詳細については、gcloud リファレンスと API リファレンスをご覧ください。

    このジョブを正常に完了できた場合は、ネットワーキング、IAM 権限、プライベート Google アクセスが正しく構成されている可能性が高いと考えられます。

  2. クイックスタートのジョブビルダーを使用してパイプラインを実行するを完了します。これにより、ジョブが Flex テンプレートとして実行されます。ワーカー VM の起動前にジョブが失敗した場合は、ランチャー VM にアクセスし、次のようなコマンドを使用してサンプル Docker イメージをダウンロードしてみてください。

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

    このコマンドが失敗した場合は、イメージのダウンロードでネットワーキングの問題が発生している可能性があります。この場合は、社内のネットワーキング チームに問い合わせてください。

  3. Google 提供の Flex テンプレートを実行し、結果を確認します。Google 提供のテンプレート ジョブが正常に完了した場合、問題は特定のカスタム テンプレート コードファイルに関連している可能性があります。この場合は、特定のコードのトラブルシューティングを続けて問題を解決する必要があります。

Docker エントリポイントを確認する

提供されたテンプレートを使用せずに、カスタム Docker イメージからテンプレートを実行する場合は、この手順を試してください。

次のコマンドを使用して、コンテナ エントリポイントを確認します。

docker inspect $TEMPLATE_IMAGE

次の出力が表示されます。

Java

/opt/google/dataflow/java_template_launcher

Python

/opt/google/dataflow/python_template_launcher

出力が異なる場合は、Docker コンテナのエントリポイントがオーバーライドされています。$TEMPLATE_IMAGE をデフォルトに戻します。

サービス アカウントの権限を確認する

メッセージにあるサービス アカウントに次の権限があることを確認します。

  • メッセージの ${file_path} にある Cloud Storage パスの読み取りと書き込み
  • メッセージの ${image_url} にある Docker イメージの読み取り

限定公開の Google アクセスを構成する

外部 IP アドレスが無効になっている場合は、Compute Engine VM が Google API とサービスで使用される一連の外部 IP アドレスに接続できるようにする必要があります。VM のネットワーク インターフェースが使用するサブネットで、限定公開の Google アクセスを有効にします。

構成の詳細は、プライベート Google アクセスの構成をご覧ください。

デフォルトでは、Compute Engine VM がネットワーク インターフェースに割り当てられた外部 IP アドレスを持たない場合、他の内部 IP アドレスの宛先にのみパケットを送信できます。

ランチャー プログラムを終了できないかどうかを確認する

パイプラインを構築するプログラムは、パイプラインの起動前に終了する必要があります。ポーリング エラーは、時間がかかりすぎたことを示している可能性があります。

コード内で原因を特定するには、次のような方法があります。

  • ジョブのログを調べ、完了までに時間がかかっているオペレーションがあるかどうかを確認します。たとえば、外部リソースのリクエストなどです。
  • プログラムの終了をブロックしているスレッドがないことを確認します。一部のクライアントが独自のスレッドを作成している場合があります。このようなクライアントがシャットダウンされない場合、プログラムはこれらのスレッドが参加するまで待機します。

テンプレートを使用しない直接起動するパイプラインにこうした制限はありません。したがって、パイプラインが直接動作してもテンプレートとして機能していない場合は、テンプレートの使用が根本原因である可能性があります。テンプレートの問題を見つけて修正すると、問題が解決することがあります。

必要なパイプライン オプションが抑制されているかどうかを確認する

Flex テンプレートを使用する場合、パイプラインの初期化時にパイプライン オプションを構成できますが、すべてを構成できるわけではありません。詳細については、このドキュメントのジョブファイルの読み取りに失敗したセクションをご覧ください。

Python ユーザー: 依存関係の管理

requirements.txt ファイルで追加の依存関係を指定する Python Flex テンプレート ジョブを実行すると、ジョブの起動に失敗することがあります。このエラーは、要件ファイルで指定された依存関係のダウンロードまたはインストールが、Flex テンプレートの起動に割り当てられた時間よりも長くかかる場合に発生します。

ジョブのパフォーマンスを最適化するには、テンプレートの作成時に依存関係をパッケージ化して、テンプレートの起動時に依存関係をダウンロードまたはインストールする必要がないようにします。詳細については、「Flex テンプレートを構成する」の Python のパッケージ依存関係をご覧ください。

ジョブ起動エラー

次のセクションでは、ジョブの起動の失敗原因となる一般的なエラーと、エラーの解決またはトラブルシューティングの手順について説明します。

早期起動に関する問題

テンプレートの起動プロセスが初期段階で失敗した場合、通常の Flex テンプレート ログを使用できない場合があります。起動の問題を調査するには、テンプレート ランチャー VM でシリアルポート ロギングを有効にします。

Java テンプレートのロギングを有効にするには、enableLauncherVmSerialPortLogging オプションを true に設定します。Python テンプレートと Go テンプレートのロギングを有効にするには、enable_launcher_vm_serial_port_logging オプションを true に設定します。 Google Cloud コンソールでは、このパラメータは [オプション パラメータ] に「Enable Launcher VM Serial Port Logging」と表示されます。

テンプレート ランチャー VM のシリアルポート出力ログを Cloud Logging で確認できます。特定のランチャー VM のログを検索するには、クエリ resource.type="gce_instance" "launcher-number" を使用します。ここで、number は YYYMMDD 形式の現在の日付で始まる値です。

組織のポリシーにより、シリアルポート出力のロギングを有効にすることが禁止されている場合があります。

ジョブファイルの読み取りに失敗した

Flex テンプレートからジョブを実行しようとした際に、ジョブが失敗して、次のエラーが発生する場合があります。

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

このエラーは、必要なパイプラインの初期化オプションが上書きされた場合に発生します。Flex テンプレートを使用する場合、パイプラインの初期化時にパイプライン オプションを構成できますが、すべてを構成できるわけではありません。Flex テンプレートに必要なコマンドライン引数が上書きされると、テンプレート ランチャーから渡されたパイプライン オプションがジョブによって無視、オーバーライド、または破棄される可能性があります。ジョブの起動に失敗するか、Flex テンプレートを使用していないジョブが起動する可能性があります。

この問題を回避するため、パイプラインの初期化中に、ユーザーコードまたは metadata.json ファイルで次のパイプライン オプションを変更しないでください。

Java

  • runner
  • project
  • jobName
  • templateLocation
  • region

Python

  • runner
  • project
  • job_name
  • template_location
  • region

Go

  • runner
  • project
  • job_name
  • template_location
  • region

結果ファイルの読み取りに失敗した

Flex テンプレートからジョブを実行しようとした際に、ジョブが失敗して、次のエラーが発生する場合があります。

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

このエラーは、Compute Engine のデフォルトのサービス アカウントに、Flex テンプレートの実行に必要なすべての権限がない場合に発生します。必要な権限の一覧については、Flex テンプレートを実行する権限をご覧ください。

リソースの権限が拒否された

Flex テンプレートからジョブを実行しようとした際に、ジョブが失敗して、次のエラーが発生する場合があります。

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

このエラーは、使用したサービス アカウントに、Flex テンプレートの実行に必要なリソースにアクセスする権限がない場合に発生します。

この問題を回避するには、サービス アカウントに必要な権限があることを確認します。必要に応じて、サービス アカウントの権限を調整します。

フラグは指定されているが定義されていない

worker_machine_type パイプライン オプションを使用して Go Flex テンプレートを実行しようとすると、パイプラインが次のエラーで失敗します。

flag provided but not defined: -machine_type

このエラーは、Apache Beam Go SDK バージョン 2.47.0 以前の既知の問題が原因で発生します。この問題を解決するには、Apache Beam Go バージョン 2.48.0 以降にアップグレードしてください。

リモート ジョブ サーバー JAR を取得できない

インターネットに接続していないときに Flex テンプレートからジョブを実行しようとすると、ジョブが失敗して次のエラーが発生することがあります。

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

このエラーは、VM がインターネットから Apache Beam Java パッケージをダウンロードできないために発生します。このパッケージは、Flex テンプレートを使用して多言語ジョブを実行する場合に必要となります。

この問題を解決するには、次のいずれかの変更を行います。

  • インターネットに接続します。インターネットに接続すると、ジョブが必要なファイルにアクセスできます。

  • ジョブがローカルでアクセスできるように、Apache Beam Java パッケージをローカル ディレクトリに含めます。ディレクトリ /root/.apache_beam/cache/jars/ にファイルを配置します。例: /root/.apache_beam/cache/jars/beam-sdks-java-io-expansion-service-SDK_VERSION.jar

指定されたパスからファイルシステムを取得できない

Flex テンプレートからジョブを実行しようとした際に、ジョブが失敗して、次のエラーが発生する場合があります。

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

このエラーは、ジョブが Flex テンプレートのコンテナ イメージを使用し、このコンテナ イメージに Java インストールが含まれていない場合に発生します。

この問題を解決するには、Dockerfile に次の行を追加します。

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

このコマンドは、コンテナ環境に Java をインストールします。

Flex テンプレート ランチャーの遅延

Flex テンプレート ジョブを送信すると、ジョブ リクエストは Spanner キューに入ります。テンプレート ランチャーは、Spanner キューからジョブを取得し、テンプレートを実行します。Spanner にメッセージ バックログがある場合、ジョブを送信してからジョブが起動するまでに大幅な遅延が発生することがあります。

この問題を回避するには、別のリージョンから Flex テンプレートを起動します。

テンプレート パラメータが無効

gcloud CLI を使用して、Google 提供のテンプレートを使用するジョブを実行すると、次のエラーが発生します。

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

このエラーは、Google 提供のテンプレートの一部が defaultSdkHarnessLog オプションと defaultWorkerLog オプションをサポートしていないために発生します。

回避策として、テンプレート仕様ファイルを Cloud Storage バケットにコピーします。このファイルに次のパラメータを追加します。

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

この変更をテンプレート ファイルに行ったら、次のコマンドでテンプレートを実行します。

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

次の値を置き換えます。

  • BUCKET_NAME: Cloud Storage バケットの名前
  • FILENAME: テンプレート仕様ファイルの名前

Flex テンプレート ランチャー ログの重大度が間違っている

カスタム Flex テンプレートの起動に失敗すると、次のメッセージが重大度 ERROR でログファイルに記録されます。

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

通常、このメッセージの前に起動失敗の根本原因が重大度 INFO でログに記録されます。Flex テンプレート ランチャーには、Apache Beam アプリケーションによって生成されたログメッセージから重大度の詳細を抽出する方法がありません。このため、このログレベルが正しくない可能性があります。

ランチャーログのメッセージの正しい重大度を確認するには、ログをプレーンテキストではなく JSON 形式で生成するようにテンプレートを構成します。この構成により、テンプレート ランチャーはログ メッセージの正しい重大度を抽出できます。次のメッセージ構造を使用します。

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

Java では、カスタム JSON アペンダー実装で Logback ロガーを使用できます。詳細については、GitHub の Logback の構成例と JSON アペンダーのコードの例をご覧ください。

この問題は、パイプラインの起動時に Flex テンプレート ランチャーによって生成されたログにのみ影響します。起動に成功し、パイプラインが実行されている場合、Dataflow ワーカーによって生成されるログには適切な重大度が設定されます。

Google 提供のテンプレートは、この JSON ロギング アプローチを使用しているため、ジョブの開始時に正しい重大度が表示されます。