使用資料取樣功能觀察管道資料

資料取樣功能可讓您觀察資料在 Dataflow 管道每個步驟中的狀態。這項資訊會顯示執行中或已完成作業的實際輸入和輸出內容，有助於排解管道問題。

資料取樣的用途包括：

  • 在開發期間，查看整個管道中產生的元素。

  • 如果管道擲回例外狀況，請查看與該例外狀況相關的元素。

  • 偵錯時，請查看轉換的輸出內容，確保輸出內容正確無誤。

  • 瞭解管道的行為，不必檢查管道程式碼。

  • 工作完成後，您可以稍後查看取樣元素，或比較樣本資料與先前的執行結果。

總覽

Dataflow 可以透過下列方式對管道資料進行取樣：

  • 週期性取樣。使用這類取樣方式時，Dataflow 會在工作執行期間收集樣本。您可以使用樣本資料檢查管道是否正常處理元素，並診斷執行階段問題，例如熱鍵或輸出內容不正確。詳情請參閱本文的「使用週期性資料取樣」一節。

  • 例外狀況取樣。如果管道擲回例外狀況，Dataflow 就會收集樣本。您可以透過這些樣本查看發生例外狀況時處理的資料。例外狀況取樣功能預設為啟用，但可以停用。詳情請參閱本文的「使用例外狀況取樣」一節。

Dataflow 會將取樣元素寫入 gcpTempLocation (適用於 Java) 和 temp_location (適用於 Python 和 Go) 管道選項指定的 Cloud Storage 路徑。您可以在 Google Cloud 控制台中查看樣本資料，或檢查 Cloud Storage 中的原始資料檔案。檔案會保留在 Cloud Storage 中，直到您刪除為止。

資料取樣作業是由 Dataflow 工作站執行。取樣是盡力而為的程序。如果發生暫時性錯誤，系統可能會捨棄樣本。

需求條件

如要使用資料取樣功能，必須啟用 Runner v2。詳情請參閱「啟用 Dataflow Runner v2」。

如要在 Google Cloud 控制台中查看樣本資料，您需要下列 Identity and Access Management 權限：

  • storage.buckets.get
  • storage.objects.get
  • storage.objects.list

如要使用週期性取樣功能，必須安裝下列 Apache Beam SDK：

  • Apache Beam Java SDK 2.47.0 以上版本
  • Apache Beam Python SDK 2.46.0 以上版本
  • Apache Beam Go SDK 2.53.0 以上版本

例外狀況取樣功能需要下列 Apache Beam SDK：

  • Apache Beam Java SDK 2.51.0 以上版本
  • Apache Beam Python SDK 2.51.0 以上版本
  • Apache Beam Go SDK 不支援例外狀況取樣。

從這些 SDK 開始，Dataflow 預設會為所有工作啟用例外狀況取樣功能。

使用週期性資料取樣

本節說明如何在作業執行期間持續取樣管道資料。

啟用定期資料取樣

週期性取樣功能預設為停用。如要啟用這項功能，請設定下列管道選項：

Java

--experiments=enable_data_sampling

Python

--experiments=enable_data_sampling

Go

--experiments=enable_data_sampling

您可以透過程式設定選項，也能利用指令列指定。詳情請參閱「設定實驗性管道選項」。

執行 Dataflow 範本時，請使用 additional-experiments 旗標啟用資料取樣：

--additional-experiments=enable_data_sampling

啟用週期性取樣後，Dataflow 會從工作圖表中的每個 PCollection 收集樣本。取樣率約為每 30 秒一個樣本。

視資料量而定，定期資料取樣可能會大幅增加效能負擔。因此，建議您只在測試期間啟用定期取樣功能，並針對實際工作負載停用這項功能。

查看樣本資料

如要在 Google Cloud 控制台中查看樣本資料，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的 Dataflow「Jobs」(工作) 頁面。

    前往工作

  2. 選取職缺。

  3. 按一下底部面板上的 ，展開記錄面板。

  4. 按一下「資料抽樣」分頁標籤。

  5. 在「Step」(步驟) 欄位中，選取管道步驟。也可以選取工作圖表中的步驟。

  6. 在「Collection」(集合) 欄位中，選擇 PCollection。

如果 Dataflow 已收集該 PCollection 的樣本，分頁中就會顯示樣本資料。分頁會顯示每個樣本的建立日期和輸出元素。輸出元素是集合元素的序列化表示法，包括元素資料、時間戳記，以及視窗和窗格資訊。

以下範例顯示取樣元素。

Java

TimestampedValueInGlobalWindow{value=KV{way, [21]},
timestamp=294247-01-09T04:00:54.775Z, pane=PaneInfo{isFirst=true, isLast=true,
timing=ON_TIME, index=0, onTimeIndex=0}}

Python

(('THE', 1), MIN_TIMESTAMP, (GloblWindow,), PaneInfo(first: True, last: True,
timing: UNKNOWN, index: 0, nonspeculative_index: 0))

Go

KV<THE,1> [@1708122738999:[[*]]:{3 true true 0 0}]

下圖顯示樣本資料在Google Cloud 控制台中的顯示方式。

Google Cloud 控制台中的樣本資料

使用例外狀況取樣

如果管道擲回未處理的例外狀況，您可以查看例外狀況和與該例外狀況相關聯的輸入元素。使用支援的 Apache Beam SDK 時，系統預設會啟用例外狀況取樣功能。

查看例外狀況

如要查看例外狀況，請執行下列步驟：

  1. 前往 Google Cloud 控制台的 Dataflow「Jobs」(工作) 頁面。

    前往工作

  2. 選取職缺。

  3. 如要展開「記錄」面板，請按一下「記錄」面板上的「切換面板」圖示 。

  4. 按一下「資料抽樣」分頁標籤。

  5. 在「Step」(步驟) 欄位中，選取管道步驟。也可以選取工作圖表中的步驟。

  6. 在「Collection」(集合) 欄位中，選擇 PCollection。

    「例外狀況」欄包含例外狀況詳細資料。例外狀況沒有輸出 元素。而是包含訊息 Failed to process input element: INPUT_ELEMENT，其中 INPUT_ELEMENT 是相關的輸入元素。輸出元素資料欄會顯示這則訊息。

  7. 如要在新視窗中查看輸入樣本和例外狀況詳細資料，請按一下「在新視窗中開啟」。

下圖顯示例外狀況在Google Cloud 控制台中的顯示方式。

Google Cloud 控制台中的例外狀況樣本

停用例外狀況取樣

如要停用例外狀況取樣，請設定下列管道選項：

Java

--experiments=disable_always_on_exception_sampling

Python

--experiments=disable_always_on_exception_sampling

您可以透過程式設定選項，也能利用指令列指定。詳情請參閱「設定實驗性管道選項」。

執行 Dataflow 範本時，請使用 additional-experiments 旗標停用例外狀況取樣：

--additional-experiments=disable_always_on_exception_sampling

安全性考量

Dataflow 會將樣本資料寫入您建立及管理的 Cloud Storage bucket。使用 Cloud Storage 的安全功能，確保資料安全無虞。請特別考慮採取下列額外安全措施：

您也可以模糊化 PCollection 資料類型中的個別欄位，這樣原始值就不會出現在樣本資料中：

  • Python：覆寫 __repr__ 或 __str__ 方法。
  • Java：覆寫 toString 方法。

不過，除非修改連接器原始碼，否則無法對 I/O 連接器的輸入和輸出內容進行模糊處理。

帳單

Dataflow 執行資料取樣時，系統會向您收取 Cloud Storage 資料儲存費用，以及 Cloud Storage 的讀取和寫入作業費用。詳情請參閱 Cloud Storage 定價。

每個 Dataflow 工作站都會批次寫入樣本，因此每個批次會產生一次讀取作業和一次寫入作業。

疑難排解

本節提供使用資料取樣時的常見問題。

權限錯誤

如果沒有權限查看樣本， Google Cloud 控制台會顯示下列錯誤：

You don't have permission to view a data sample.

如要解決這個錯誤，請確認您具備必要的 IAM 權限。如果錯誤仍會發生，您可能受到 IAM 拒絕政策限制。

我沒有看到任何樣本

如果沒有看到任何樣本，請檢查下列事項：

  1. 請設定 enable_data_sampling 選項，確保已啟用資料取樣。請參閱「啟用資料取樣」。
  2. 確認你使用的是 Runner v2
  3. 確認工作人員已開始工作。取樣作業會在工作人員開始工作後啟動。
  4. 確認工作和工作人員狀態良好。
  5. 請仔細檢查專案的 Cloud Storage 配額。如果超出 Cloud Storage 儲存空間配額上限，Dataflow 就無法寫入範例資料。
  6. 資料取樣無法從可疊代物件取樣。系統不會提供這類串流的樣本。

後續步驟