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

資料取樣功能可讓您觀察資料在 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 控制台中查看取樣資料，您必須具備下列身分與存取權管理權限：

• 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 預設會為所有工作啟用例外狀況取樣功能。

使用定期資料取樣

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

啟用定期資料取樣

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

--experiments=enable_data_sampling

--experiments=enable_data_sampling

--experiments=enable_data_sampling

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

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

--additional-experiments=enable_data_sampling

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

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

查看樣本資料

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

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

   前往「Jobs」(工作) 頁面

2. 選取職務。

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

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

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

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

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

以下範例顯示取樣元素。

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}}

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

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

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

使用例外狀況取樣

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

查看例外狀況

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

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

   前往「Jobs」(工作) 頁面

2. 選取職務。

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

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

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

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

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

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

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

停用例外狀況取樣

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

--experiments=disable_always_on_exception_sampling

--experiments=disable_always_on_exception_sampling

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

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

--additional-experiments=disable_always_on_exception_sampling

安全性考量

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

• 使用客戶自行管理的加密金鑰 (CMEK) 將 Cloud Storage bucket 加密。如要進一步瞭解如何選擇加密選項，請參閱「選擇適合您需求的加密方式」。
• 在 Cloud Storage bucket 中設定存留時間 (TTL)，讓資料檔案在一段時間後自動刪除。詳情請參閱「為值區設定生命週期設定」。
• 將 IAM 權限指派給 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. 資料取樣無法從可疊代物件取樣。系統不會提供這類串流的樣本。

後續步驟

• 開發及測試 Dataflow pipeline
• 使用 Dataflow 監控介面