執行原生查詢執行資格工具

如要找出可透過原生查詢執行 (NQE) 縮短執行時間的批次工作負載，可以使用資格工具。這項工具會分析 Spark 事件記錄，估算潛在的執行階段節省量，並找出 NQE 引擎不支援的任何作業。

Google Cloud 提供兩種執行資格分析的方法：資格工作和資格指令碼。對於大多數使用者，建議採用資格工作，這項工作會自動探索及分析批次工作負載。替代資格指令碼可用於分析已知事件記錄檔的特定用途。請選擇最符合您用途的方法：

  • 資格職缺 (建議)：這是主要且建議的方法。 這項 PySpark 工作會自動探索及分析一或多個 Google Cloud 專案和區域的近期批次工作負載。如要執行廣泛分析，但不需要手動尋找個別事件記錄檔，請使用這個方法。這個方法非常適合大規模評估 NQE 適用性。

  • 資格指令碼 (替代方法)：這是進階或特定用途的替代方法。這個殼層指令碼會分析單一 Spark 事件記錄檔，或特定 Cloud Storage 目錄中的所有事件記錄。如要分析事件記錄，請使用這個方法，並提供 Cloud Storage 路徑。

資格工作

資格工作會以程式輔助方式掃描 Serverless for Apache Spark 批次工作負載，並提交分散式分析工作，簡化大規模分析作業。這項工具會評估整個機構的工作，因此您不必手動尋找及指定事件記錄路徑。

授予 IAM 角色

如要讓資格工作存取批次工作負載中繼資料，並在 Cloud Logging 中讀取 Spark 事件記錄，執行工作負載的服務帳戶必須在所有待分析的專案中，獲得下列 IAM 角色：

提交資格工作

您可以使用 gcloud CLI 工具提交資格工作。這項工作包含 PySpark 指令碼和 JAR 檔案，這些檔案託管在公開的 Cloud Storage bucket 中。

您可以在下列任一執行環境中執行工作：

  • 以 Serverless for Apache Spark 批次工作負載的形式。這是簡單的獨立工作執行作業。

  • 以在 Dataproc on Compute Engine 叢集上執行的工作形式。這種方法有助於將工作整合至工作流程。

工作引數

引數 說明 是否必要 預設值
--project-ids 單一專案 ID 或以半形逗號分隔的 Google Cloud 專案 ID 清單，用於掃描批次工作負載。 否 執行資格工作所在的專案。
--regions 單一區域或以半形逗號分隔的區域清單，用於掃描指定專案。 否 指定專案中的所有區域。
--start-time 用於篩選批次的開始日期。系統只會分析這個日期 (格式：YYYY-MM-DD) 當天或之後建立的批次。 否 未套用開始日期篩選條件。
--end-time 用於篩選批次的結束日期。系統只會分析在此日期 (格式：YYYY-MM-DD) 當天或之前建立的批次。 否 未套用結束日期篩選器。
--limit 每個區域要分析的批次數量上限。系統會優先分析最近的批次。 否 系統會分析符合其他篩選條件的所有批次。
--output-gcs-path 結果檔案的寫入 Cloud Storage 路徑 (例如 gs://your-bucket/output/)。 是 無
--input-file 用於大量分析的文字檔案 Cloud Storage 路徑。如果提供這項引數，系統會覆寫所有其他定義範圍的引數 (--project-ids、--regions、--start-time、--end-time、--limit)。 否 無

資格條件工作範例

  • Serverless for Apache Spark 批次工作，可執行簡單的臨時分析。工作引數會列在 -- 分隔符號之後。

    gcloud dataproc batches submit pyspark gs://qualification-tool/performance-boost-qualification.py \
    --project=PROJECT_ID \
    --region=REGION \
    --jars=gs://qualification-tool/dataproc-perfboost-qualification-1.2.jar \
    -- \
    --project-ids=COMMA_SEPARATED_PROJECT_IDS \
    --regions=COMMA_SEPARATED_REGIONS \
    --limit=MAX_BATCHES \
    --output-gcs-path=gs://BUCKET

  • 這項 Serverless for Apache Spark 批次工作會分析 us-central1 地區 sample_project 中最多 50 個最近的批次，結果會寫入 Cloud Storage 中的 bucket。工作引數會列在 -- 分隔符號之後。

    gcloud dataproc batches submit pyspark gs://qualification-tool/performance-boost-qualification.py \
    --project=PROJECT_ID \
    --region=US-CENTRAL1 \
    --jars=gs://qualification-tool/dataproc-perfboost-qualification-1.2.jar \
    -- \
    --project-ids=PROJECT_ID \
    --regions=US-CENTRAL1 \
    --limit=50 \
    --output-gcs-path=gs://BUCKET/

  • 提交至 Dataproc 叢集的 Dataproc on Compute Engine 工作，用於大規模、可重複或自動化分析工作流程中的大量分析。工作引數會放在 INPUT_FILE 中，並上傳至 Cloud Storage 中的 BUCKET。這個方法非常適合在單次執行中，掃描不同專案和區域的不同日期範圍或批次限制。

    gcloud dataproc jobs submit pyspark gs://qualification-tool/performance-boost-qualification.py \
    --cluster=CLUSTER_NAME \
    --region=REGION \
    --jars=gs://qualification-tool/dataproc-perfboost-qualification-1.2.jar \
    -- \
    --input-file=gs://INPUT_FILE \
    --output-gcs-path=gs://BUCKET

    注意：

    INPUT_FILE：檔案中的每一行代表不同的分析要求，並使用單一字母標記及其值的格式，例如 -p PROJECT-ID -r REGION -s START_DATE -e END_DATE -l LIMITS。

    輸入檔案內容範例：

    -p project1 -r us-central1 -s 2024-12-01 -e 2024-12-15 -l 100
-p project2 -r europe-west1 -s 2024-11-15 -l 50

    這些引數會引導工具分析下列兩個範圍：

    • 2025 年 12 月 1 日至 2025 年 12 月 15 日期間，在 us-central1 地區的 project1 中建立最多 100 個批次。
    • 在 2025 年 11 月 15 日當天或之後建立的 europe-west1 區域中，專案 2 最多可有 50 個批次。

資格賽腳本

如果您有要分析的特定 Spark 事件記錄的直接 Cloud Storage 路徑，請使用這個方法。這個方法需要您在本機電腦或 Compute Engine VM 上下載並執行殼層指令碼 run_qualification_tool.sh，且該 VM 已設定為可存取 Cloud Storage 中的事件記錄檔。

請按照下列步驟，針對 Serverless for Apache Spark 批次工作負載事件檔案執行指令碼。

1. 將 run_qualification_tool.sh 複製到包含要分析的 Spark 事件檔案的本機目錄。

  1. 執行資格指令碼，分析指令碼目錄中的一個或一組事件檔案。

    ./run_qualification_tool.sh -f EVENT_FILE_PATH/EVENT_FILE_NAME \
    -o CUSTOM_OUTPUT_DIRECTORY_PATH \
    -k SERVICE_ACCOUNT_KEY  \
    -x MEMORY_ALLOCATEDg  \
    -t PARALLEL_THREADS_TO_RUN

    旗標和值：

    -f (必要)：請參閱「Spark 事件檔案位置」，找出 Spark 工作負載事件檔案。

    • EVENT_FILE_PATH (必要，除非指定 EVENT_FILE_NAME)：要分析的事件檔案路徑。如未提供，系統會假設事件檔案路徑為目前目錄。

    • EVENT_FILE_NAME (必要，除非指定 EVENT_FILE_PATH)： 要分析的事件檔案名稱。如未提供，系統會分析 EVENT_FILE_PATH 中以遞迴方式找到的事件檔案。

    -o(選用)：如果未提供，工具會在目前目錄下建立或使用現有的 output 目錄，放置輸出檔案。

    • CUSTOM_OUTPUT_DIRECTORY_PATH：輸出檔案的輸出目錄路徑。

    -k (選用)：

    • SERVICE_ACCOUNT_KEY：JSON 格式的服務帳戶金鑰 (如需存取 EVENT_FILE_PATH)。

    -x (選用)：

    • MEMORY_ALLOCATED：要分配給工具的記憶體 (以 GB 為單位)。根據預設，這項工具會使用系統中 80% 的可用記憶體，以及所有可用的機器核心。

    -t(選用)：

    • PARALLEL_THREADS_TO_RUN：工具執行的平行執行緒數量。根據預設，這項工具會執行所有核心。

    指令用法範例：

    ./run_qualification_tool.sh -f gs://dataproc-temp-us-east1-9779/spark-job-history \
    -o perfboost-output -k /keys/event-file-key -x 34g -t 5

    在本例中，資格工具會遍歷 gs://dataproc-temp-us-east1-9779/spark-job-history 目錄，並分析這個目錄及其子目錄中包含的 Spark 事件檔案。目錄存取權由 /keys/event-file-key 提供。這項工具會使用 34 GB memory 執行作業，並執行 5 個平行執行緒。

Spark 事件檔案位置

請執行下列任一步驟，找出 Serverless for Apache Spark 批次工作負載的 Spark 事件檔案：

  1. 在 Cloud Storage 中找出工作負載的 spark.eventLog.dir，然後下載。

    1. 如果找不到 spark.eventLog.dir，請將 spark.eventLog.dir 設為 Cloud Storage 位置，然後重新執行工作負載並下載 spark.eventLog.dir。

  2. 如果您已為批次工作設定 Spark 記錄伺服器：

    1. 前往 Spark 記錄伺服器，然後選取工作負載。
    2. 按一下「事件記錄」欄中的「下載」。

資格評估工具輸出檔案

資格工作或指令碼分析完成後，資格工具會將下列輸出檔案放在目前目錄的 perfboost-output 目錄中：

AppsRecommendedForBoost.tsv 輸出檔案

下表顯示範例 AppsRecommendedForBoost.tsv 輸出檔案的內容。其中包含每個分析應用程式的資料列。

AppsRecommendedForBoost.tsv 輸出檔案範例：

applicationId applicationName rddPercentage unsupportedSqlPercentage totalTaskTime supportedTaskTime supportedSqlPercentage recommendedForBoost expectedRuntimeReduction
app-2024081/batches/083f6196248043938-000 projects/example.com:dev/locations/us-central1
6b4d6cae140f883c0
11c8e		 0.00% 0.00% 548924253 548924253 100.00% TRUE 30.00%
app-2024081/batches/60381cab738021457-000 projects/example.com:dev/locations/us-central1
474113a1462b426bf
b3aeb		 0.00% 0.00% 514401703 514401703 100.00% TRUE 30.00%

資料欄說明：

  • applicationId：Spark 應用程式的 ApplicationID。用來識別對應的批次工作負載。

  • applicationName：Spark 應用程式的名稱。

  • rddPercentage：應用程式中 RDD 作業的百分比。 原生查詢執行作業不支援 RDD 作業。

  • unsupportedSqlPercentage: 系統不支援原生查詢執行的 SQL 作業百分比。

  • totalTaskTime：應用程式執行期間執行的所有工作累計時間。

  • supportedTaskTime：原生查詢執行作業支援的總工作時間。

下列資料欄提供重要資訊，協助您判斷原生查詢執行是否能提升批次工作負載的效益：

  • supportedSqlPercentage：原生查詢執行作業支援的 SQL 作業百分比。百分比越高，表示使用原生查詢執行功能執行應用程式時，可大幅縮短執行時間。

  • recommendedForBoost：如果 TRUE，建議使用原生查詢執行功能執行應用程式。如果 recommendedForBoost 為 FALSE，請勿在批次工作負載上使用原生查詢執行。

  • expectedRuntimeReduction：使用原生查詢執行功能執行應用程式時，預期應用程式執行階段的縮減百分比。

UnsupportedOperators.tsv 輸出檔案。

UnsupportedOperators.tsv 輸出檔案包含工作負載應用程式中使用的運算子清單，這些運算子不支援原生查詢執行。輸出檔案中的每一列都會列出不支援的運算子。

資料欄說明：

  • unsupportedOperator：原生查詢執行作業不支援的運算子名稱。

  • cumulativeCpuMs：執行運算子期間耗用的 CPU 毫秒數。這個值反映了應用程式中運算子的相對重要性。

  • count：運算子在應用程式中使用的次數。