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

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

ポーリング タイムアウトのトラブルシューティング

このセクションでは、ポーリング タイムアウトの原因を特定する手順について説明します。

ポーリング タイムアウト

Flex テンプレート ジョブから次のエラー メッセージが返される場合があります。

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

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

  1. ベース Docker イメージがオーバーライドされた。
  2. ${service_account_email} を入力するサービス アカウントに必要な権限が付与されていない。
  3. 外部 IP アドレスが無効で、VM が Google API とサービスで使用される外部 IP アドレスのセットに接続できない。
  4. グラフを作成するプログラムの完了に時間がかかっている。
  5. パイプライン オプションが上書きされている。
  6. （Python のみ）requirements.txt ファイルに問題がある。
  7. 一時的なエラーが発生した。

この問題を解決するには、まずジョブログを確認して再試行し、一時的なエラーがないか確認してください。上記の手順を試しても問題を解決できない場合は、次のトラブルシューティング手順をお試しください。

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

要件ファイルから Apache Beam を削除する（Python のみ）

Dockerfile に apache-beam[gcp] が指定された requirements.txt が含まれている場合は、ファイルから削除して個別にインストールします。次のコマンドは、この手順を実施する方法を示しています。

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

Apache Beam を要件ファイルに追加すると、起動時間が長くなり、多くの場合、タイムアウトが発生する可能性があります。

Python 使用時のポーリング タイムアウト

Flex テンプレートと Python を使用して Dataflow ジョブを実行すると、ジョブが一定期間キューに入り、実行に失敗して、次のエラーが表示される場合があります。

Timeout in polling

このエラーは、必要な依存関係のインストールに使用される requirements.txt ファイルが原因で発生します。Dataflow ジョブを実行すると、すべての依存関係がステージングされ、これらのファイルがワーカー VM からアクセス可能になります。このプロセスでは、requirements.txt ファイル内の直接的および間接的な依存関係をすべてダウンロードしてコンパイルします。一部の依存関係はコンパイルに数分かかることがあります。特に、PyArrow のコンパイルには時間がかかることがあります。PyArrow は、Apache Beam やほとんどの Cloud クライアント ライブラリで使用される間接的な依存関係です。

ジョブのパフォーマンスを最適化するには、Dockerfile またはカスタム コンテナを使用して依存関係を事前にパッケージ化します。詳細については、「Flex テンプレートを構成する」の依存関係のパッケージ化をご覧ください。

ジョブ起動エラー

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

早期起動に関する問題

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

Java テンプレートのロギングを有効にするには、enableLauncherVmSerialPortLogging オプションを true に設定します。Python テンプレートと Go テンプレートのロギングを有効にするには、enable_launcher_vm_serial_port_logging オプションを true に設定します。Google Cloud コンソールでは、このパラメータは [オプション パラメータ] に「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 with error message: ...: Unable to open template file

このエラーは、必要なパイプラインの初期化オプションが上書きされた場合に発生します。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 with error message: (ERROR_NUMBER): Unable to open template 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 ロギング アプローチを使用しているため、ジョブの開始時に正しい重大度が表示されます。