运行原生查询执行资格认证工具

如需确定哪些批量工作负载可以通过原生查询执行 (NQE) 实现更快的运行时 ，您可以使用资格验证工具。 该工具会分析 Spark 事件日志，以估算潜在的运行时节省量，并 确定 NQE 引擎不支持的任何操作。

Google Cloud 提供了两种运行资格验证分析的方法： 资格验证作业和资格验证脚本。对于大多数 用户，建议使用资格验证作业，该作业可以自动发现和分析 批量工作负载。对于分析已知事件日志文件的特定 用例，可以使用备选资格验证脚本。请选择最适合 您用例的方法：

• 资格验证作业（推荐）：这是主要方法，也是推荐的方法。 它是一个 PySpark 作业，可以自动发现和分析近期批量 工作负载，这些工作负载跨越一个或多个 Google Cloud 项目和区域。如果您想执行广泛的分析，而无需手动 查找各个事件日志文件，请使用此 方法。此方法非常适合大规模 评估 NQE 的适用性。

• 资格验证脚本（备选）：这是针对 高级或特定用例的备选方法。它是一个 Shell 脚本，用于分析单个 Spark 事件日志文件或特定 Cloud Storage 目录中的所有事件日志。如果您拥有要分析的事件 日志的 Cloud Storage 路径，请使用此方法。

资格验证作业

资格验证作业通过以编程方式 扫描 Serverless for Apache Spark 批量工作负载并提交分布式 分析作业，简化了大规模分析。该工具会评估您组织中的作业，无需您手动查找和指定事件日志路径。

授予 IAM 角色

为了让资格验证作业能够访问批量工作负载元数据 并在 Cloud Logging 中读取 Spark 事件日志，运行工作负载的服务账号必须在要分析的所有 项目中获得以下 IAM 角色：

• Dataproc Viewer (roles/dataproc.viewer)
• Logs Viewer (roles/logging.viewer)

提交资格验证作业

您可以使用 gcloud CLI 工具提交资格验证作业。 该作业包含一个 PySpark 脚本和一个 JAR 文件，它们托管在公开 Cloud Storage 存储分区中。

您可以在以下任一执行环境中运行该作业：

• 作为 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 中的存储分区。作业 参数列在 -- 分隔符之后。

  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 on Compute Engine 作业，提交到 Dataproc 集群 用于在大型、可重复或自动分析工作流中进行批量分析。 作业参数放置在上传到 Cloud Storage 中 BUCKET 的 INPUT_FILE 中。此方法非常适合在一次运行中扫描不同项目和区域中的不同日期范围或 批次限制。

  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
  

  这些参数指示该工具分析以下两个范围：

  • 在 us-central1 区域的 project1 中创建的最多 100 个批次，创建时间介于 2025 年 12 月 1 日和 2025 年 12 月 15 日之间。
  • 在 europe-west1 区域的 project2 中创建的最多 50 个批次，创建时间为 2025 年 11 月 15 日当天或之后。

资格验证脚本

如果您拥有要分析的特定 Spark 事件日志的直接 Cloud Storage 路径，请使用此方法。此方法要求您在本地机器或 Compute Engine 虚拟机上下载 并运行 Shell 脚本 run_qualification_tool.sh，该虚拟机配置了对 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：如果需要访问 EVENT_FILE_PATH，则为 JSON 格式的 服务账号密钥。

   -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 History Server ：

   1. 前往 Spark History Server，然后选择工作负载。
   2. 在事件日志 列中，点击下载 。

提示： Dataproc on Compute Engine Spark 作业分析：如需对 Dataproc on Compute Engine Spark 作业运行资格验证工具：

• 在 Cloud Storage 中找到 spark.eventLog.dir for the Dataproc on Compute Engine Spark 作业，然后下载它。
• 针对事件日志运行该工具。如果该工具建议使用 原生查询执行，请将作业迁移到 Serverless for Apache Spark 批量工作负载，然后使用原生查询执行运行工作负载。

资格验证工具输出文件

资格验证作业或脚本分析完成后，资格验证工具 会将以下输出文件放置在当前目录的 perfboost-output 目录中：

• AppsRecommendedForBoost.tsv： 以制表符分隔的应用列表，建议与原生查询执行搭配使用。

• UnsupportedOperators.tsv： 以制表符分隔的应用列表，不建议 与原生查询执行搭配使用。

资格验证工具输出文件内容以制表符分隔。 您可以使用 CSV 或 TSV 文件读取器（例如 Google 表格）查看这些文件。

注意： 当资格验证工具尝试保存输出文件时，如果输出目录中存在该文件，该工具会在保存新文件之前向文件名添加增量后缀。

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。使用此 ID 可 标识相应的批量工作负载。

• applicationName：Spark 应用的名称。

• rddPercentage：应用中 RDD 操作的百分比。 原生查询执行不支持 RDD 操作。

• unsupportedSqlPercentage: 原生查询执行不支持的 SQL 操作的百分比。

• totalTaskTime：应用运行期间执行的所有任务的累计任务时间。

• supportedTaskTime：原生查询执行支持的总任务时间。

以下列提供了重要信息，可帮助您确定 原生查询执行是否可以使您的批量工作负载受益：

• supportedSqlPercentage: 原生 查询执行支持的 SQL 操作的百分比。百分比越高，通过使用原生查询执行运行应用可以实现的运行时缩短幅度就越大 。

• recommendedForBoost: 如果为 TRUE，则建议使用原生 查询执行运行应用。如果 recommendedForBoost 为 FALSE，请勿对批量工作负载使用原生查询执行。

• expectedRuntimeReduction: 使用原生查询执行运行应用时，应用 运行时预计缩短的百分比。

UnsupportedOperators.tsv 输出文件。

UnsupportedOperators.tsv 输出文件包含工作负载应用中使用的原生查询执行不支持的运算符列表。输出文件中的每一行都列出了一个不受支持的运算符。

注意： 如果您提交 Google Cloud 支持请求并附上 UnsupportedOperators.tsv 文件，Dataproc 可以评估是否支持其他 运算符。如需了解详情，请参阅获取支持。

列说明：

• unsupportedOperator：原生查询执行不支持的运算符的名称。

• cumulativeCpuMs：执行运算符期间消耗的 CPU 毫秒数。此值反映了 运算符在应用中的相对重要性。

• count：运算符在应用中使用的次数。