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

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

Google Cloud 提供了两种运行资格认证分析的方法：资格认证作业和资格认证脚本。对于大多数用户，建议使用资格认证作业，该作业可自动发现和分析批处理工作负载。替代资格条件脚本适用于分析已知事件日志文件的特定使用情形。选择最适合您使用场景的方法：

  • 资格作业（推荐）：这是主要且推荐的方法。 它是一个 PySpark 作业，可自动发现并分析一个或多个 Google Cloud 项目和区域中的近期批处理工作负载。如果您想进行广泛的分析，但又不想手动查找各个事件日志文件，请使用此方法。此方法非常适合大规模评估 NQE 的适用性。

  • 资格认证脚本（替代方法）：这是一种适用于高级或特定用例的替代方法。这是一个 shell 脚本，用于分析单个 Spark 事件日志文件或特定 Cloud Storage 目录中的所有事件日志。如果您知道要分析的事件日志的 Cloud Storage 路径，请使用此方法。

资格验证作业

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

授予 IAM 角色

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

提交资格测试作业

您可以使用 gcloud CLI 工具提交资格认证作业。该作业包含托管在公开 Cloud Storage 存储桶中的 PySpark 脚本和 JAR 文件。

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

  • 作为 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 集群的 Dataproc on Compute Engine 作业，用于在可重复或自动化的分析工作流中进行大规模批量分析。作业实参放置在上传到 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

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

    • 在 2025 年 12 月 1 日至 2025 年 12 月 15 日期间，在 us-central1 区域的 project1 中创建的批次数量上限为 100。
    • 在 2025 年 11 月 15 日或之后创建的 europe-west1 区域中的 project2 中，最多可有 50 个批次。

资格赛脚本

如果您有要分析的特定 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：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 History Server，然后选择相应的工作负载。
    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：运算符在应用中的使用次数。