排解 Flex 範本問題

本頁面提供的疑難排解提示和偵錯策略，可協助解決您在使用 Dataflow 彈性範本時遇到的問題。這些資訊可協助您偵測輪詢逾時、判定逾時背後的原因，以及修正問題。

排解輪詢逾時問題

本節提供步驟，協助您找出輪詢逾時的原因。

輪詢逾時

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 路徑。
  • 必須能夠讀取 Docker 映像檔，並在訊息中填入 ${image_url}。

設定私人 Google 存取權

如果停用外部 IP 位址，您必須允許 Compute Engine VM 連線至 Google API 和服務所用的一組外部 IP 位址。在 VM 網路介面使用的子網路中啟用 Private Google Access。

如需設定詳細資料，請參閱設定私人 Google 存取權。

根據預設，如果 Compute Engine VM 的網路介面沒有分配到外部 IP 位址，就只能將封包傳送至其他內部 IP 位址目的地。

檢查啟動器程式是否無法結束

建構管道的程式必須完成，管道才能啟動。輪詢錯誤可能表示輪詢時間過長。

您可以採取下列幾項行動，在程式碼中找出原因：

  • 檢查工作記錄，看看是否有任何作業似乎需要很長時間才能完成。例如要求外部資源。
  • 請確認沒有任何執行緒阻礙程式結束。部分用戶可能會建立自己的執行緒，如果這些用戶未關閉，程式就會永遠等待這些執行緒加入。

直接啟動的管道 (未使用範本) 不會受到這些限制。因此，如果管道直接運作，但無法以範本形式運作，則使用範本可能是根本原因。找出範本中的問題並修正，或許就能解決問題。

確認是否已停用必要管道選項

使用 Flex 範本時，您可以在管道初始化期間設定部分管道選項，但無法設定所有選項。詳情請參閱本文的「無法讀取工作檔案」一節。

從需求檔案中移除 Apache Beam (僅限 Python)

如果 Dockerfile 包含 requirements.txt 和 apache-beam[gcp]，請從檔案中移除，並另外安裝。下列指令說明如何完成這個步驟：

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

將 Apache Beam 放入需求檔案可能會導致啟動時間過長，通常會導致逾時。

使用 Python 時的輪詢逾時

如果您使用彈性範本和 Python 執行 Dataflow 工作，工作可能會排隊一段時間，然後無法執行，並顯示下列錯誤：

Timeout in polling

用於安裝必要依附元件的 requirements.txt 檔案會導致錯誤。啟動 Dataflow 工作時，系統會先暫存所有依附元件，讓工作站 VM 能夠存取這些檔案。這個程序會下載並編譯 requirements.txt 檔案中的每個直接和間接依附元件。部分依附元件可能需要幾分鐘才能編譯完成。請注意，PyArrow 可能需要一段時間才能編譯完成。PyArrow 是 Apache Beam 和大多數 Cloud Client Libraries 使用的間接依附元件。

如要提升工作效能，請使用 Dockerfile 或自訂容器預先封裝依附元件。詳情請參閱「設定 Flex 範本」一文中的「套件依附元件」。

工作啟動失敗

以下章節列出導致工作啟動失敗的常見錯誤，以及解決或排解錯誤的步驟。

啟動初期問題

如果範本啟動程序在早期階段失敗，可能無法取得一般彈性範本記錄。如要調查啟動問題，請為範本啟動器 VM 啟用序列埠記錄。

如要為 Java 範本啟用記錄功能，請將 enableLauncherVmSerialPortLogging 選項設為 true。如要為 Python 和 Go 範本啟用記錄功能，請將 enable_launcher_vm_serial_port_logging 選項設為 true。在 Google Cloud 控制台中，這個參數會列於「Optional parameters」(選用參數)，名稱為「Enable Launcher VM Serial Port Logging」(啟用啟動器 VM 序列埠記錄)。

您可以在 Cloud Logging 中查看範本啟動器 VM 的序列埠輸出記錄。如要尋找特定啟動器 VM 的記錄，請使用查詢 resource.type="gce_instance" "launcher-number"，其中 number 以目前日期開頭，格式為 YYYMMDD。

機構政策可能禁止您啟用序列埠輸出記錄功能。

無法讀取工作檔案

嘗試從彈性範本執行工作時，工作可能會失敗，並顯示下列錯誤訊息：

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 範本所需的指令列引數，工作可能會忽略、覆寫或捨棄範本啟動器傳遞的管道選項。工作可能無法啟動，或啟動未使用彈性範本的工作。

為避免發生這個問題，請勿在管道初始化期間，變更使用者程式碼或 metadata.json 檔案中的下列管道選項：

Java

  • runner
  • project
  • jobName
  • templateLocation
  • region

Python

  • runner
  • project
  • job_name
  • template_location
  • region

Go

  • runner
  • project
  • job_name
  • template_location
  • region

無法讀取結果檔案

嘗試從彈性範本執行工作時，工作可能會失敗，並顯示下列錯誤訊息：

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

如果Compute Engine 預設服務帳戶沒有執行彈性範本所需的所有權限，就會發生這個錯誤。如需必要權限清單，請參閱「執行彈性範本的權限」。

資源權限遭拒

嘗試從彈性範本執行工作時，工作可能會失敗，並顯示下列錯誤訊息：

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

如果未連上網際網路，並嘗試從彈性範本執行工作，工作可能會失敗並顯示下列錯誤：

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。

無法從指定路徑取得檔案系統

嘗試從彈性範本執行工作時，工作可能會失敗，並顯示下列錯誤訊息：

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

如果作業使用彈性範本容器映像檔，但該映像檔未安裝 Java，就會發生這個錯誤。

如要解決這個問題，請在 Dockerfile 中新增下列程式碼：

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

這個指令會在容器環境中安裝 Java。

Flex 範本啟動器延遲

提交 Flex 範本工作時，工作要求會進入 Spanner 佇列。範本啟動器會從 Spanner 佇列中擷取工作，然後執行範本。如果 Spanner 有訊息積壓，您提交工作和工作啟動之間可能會出現明顯延遲。

如要解決這個問題，請從其他區域啟動彈性範本。

範本參數無效

嘗試使用 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 bucket 的名稱
  • 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 附加程式範例程式碼。

這項問題只會影響管道啟動時，由彈性範本啟動器產生的記錄。啟動成功且管道正在執行時，Dataflow 工作站產生的記錄會具有適當的嚴重程度。

Google 提供的範本 會在啟動作業時顯示正確的嚴重程度，因為 Google 提供的範本會使用這種 JSON 記錄方法。