Publish op-time companions at MODERATE metrics level

[binmahone]

Description

Keep spark.rapids.sql.metrics.level defaulting to MODERATE, while publishing the semaphore-excluded companion for the new operator-time metrics at that level.

This introduces a dedicated createOpTime factory path and applies it to regular GPU operators, scans, columnar-to-row, Python execution, write statistics, and shuffle read/write operator-time metrics. Other timing metrics continue to publish their semaphore-excluded companions only at DEBUG.

The goal is to make quantitative event-log analysis of raw operator time versus operator time excluding GPU semaphore wait available from the default metrics level, without asking customers to enable DEBUG and rerun the workload. This is the narrower follow-up to #15400, which changed the global default to DEBUG.

Serialized task-result impact

Each published operator-time metric adds exactly one accumulator companion. A focused Spark closure-serializer test using 100 operator-time metrics measured:

• Without companions: 6,989 bytes
• With companions: 13,316 bytes
• Delta: 6,327 bytes total, or approximately 63.3 bytes per operator-time metric per task

This measurement isolates the serialized accumulator payload; it is not an end-to-end DirectTaskResult size measurement. Actual task-result size depends on the executed plan, the number of published SQL metrics, Spark version, and serializer.

Testing

• mvn -B -pl sql-plugin -am test -DwildcardSuites=com.nvidia.spark.rapids.GpuMetricFactorySuite,com.nvidia.spark.rapids.GpuMetricsSuite
  • 5 tests passed
• mvn -B -pl tests -am test -DwildcardSuites=com.nvidia.spark.rapids.GpuMetricCompanionSuite
  • 3 ScalaTest tests passed; reactor build succeeded
• mvn -B -N verify -DskipTests
  • RAT: 0 unapproved or unknown files
  • Scalastyle: 1,700 files processed, 0 errors, 0 warnings

Documentation

• Updated for new or modified user-facing features or behaviors
• No user-facing change

Testing

• Added or modified tests to cover new code paths
• Covered by existing tests
• Not required

Performance

• Tests ran and results are added in the PR description
• Issue filed with a link in the PR description
• Not required

[greptile-apps]

Spark 4.2 scan companion omitted

When a DataSource V2 batch scan runs on Spark 4.2 at the default MODERATE metrics level, its allMetrics override bypasses this changed map and still constructs OP_TIME_NEW through the ordinary timing factory, so opTimeNew_exSemWait is absent from event logs.

Knowledge Base Used: Plugin Entrypoint and GPU Overrides

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[binmahone]

Fixed in b363d91. The Spark 4.2 GpuBatchScanExec allMetrics override now uses createOpTimeMetric, and a Spark 4.2-specific suite verifies that both opTimeNew and opTimeNew_exSemWait are published at MODERATE.

Validation: mvn -B -f scala2.13/pom.xml -Dbuildver=420 -pl sql-plugin -Dsuites=com.nvidia.spark.rapids.shims.spark420.GpuBatchScanExecSuite test and the repository-wide scalastyle check both pass.

[greptile-apps]

Greptile Summary

The PR keeps the default metrics level at MODERATE while publishing semaphore-excluded companions for operator-time metrics.

• Adds a dedicated operator-time metric factory with companions enabled at MODERATE.
• Migrates GPU operators, scans, Python execution, write statistics, and shuffle timing to the new factory.
• Updates the Spark 4.2 batch-scan override, resolving the previously reported missing companion.
• Adds focused metric-factory, serialization-size, and Spark 4.2 scan coverage.
• Updates the user-facing metrics configuration documentation.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the prior Spark 4.2 batch-scan omission is corrected by routing its overridden operator-time metric through the new companion-producing factory.

Important Files Changed

Filename	Overview
sql-plugin/src/main/scala/com/nvidia/spark/rapids/GpuMetrics.scala	Adds the dedicated operator-time factory while preserving DEBUG-only companions for other metric types.
sql-plugin/src/main/scala/com/nvidia/spark/rapids/GpuExec.scala	Routes the standard GPU operator-time metric through the new MODERATE-level companion path.
sql-plugin/src/main/spark420/scala/com/nvidia/spark/rapids/shims/GpuBatchScanExec.scala	Updates the Spark 4.2 scan-specific metrics override to publish the semaphore-excluded operator-time companion.
sql-plugin/src/test/scala/com/nvidia/spark/rapids/GpuMetricFactorySuite.scala	Covers companion publication by metrics level and measures serialized accumulator overhead.
sql-plugin/src/test/spark420/scala/com/nvidia/spark/rapids/shims/spark420/GpuBatchScanExecSuite.scala	Verifies that the Spark 4.2 batch scan exposes both operator-time metrics at MODERATE.

_{Reviews (2): Last reviewed commit: "Publish Spark 4.2 batch scan op-time com..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This PR makes operator-time metrics publish their semaphore-excluded companion (the “exSemWait” accumulator) at the default MODERATE metrics level, while leaving spark.rapids.sql.metrics.level defaulting to MODERATE. This improves event-log–based analysis by exposing both raw operator time and operator time excluding GPU semaphore wait without requiring a DEBUG rerun.

Changes:

• Introduces GpuMetricFactory.createOpTime(...) and GpuExec.createOpTimeMetric(...) to create op-time metrics whose semaphore-excluded companion is enabled at MODERATE.
• Switches operator-time metric creation across core execs (operators, scans, shuffle read/write, Python exec, columnar-to-row, and write stats) to use the new op-time factory path.
• Updates configuration docs and adds a unit test to verify companion publication behavior and validate the per-operator serialized-accumulator overhead.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
sql-plugin/src/main/scala/com/nvidia/spark/rapids/GpuMetrics.scala	Adds createOpTime and refactors internal factory logic to control companion publication level per metric kind.
sql-plugin/src/main/scala/com/nvidia/spark/rapids/GpuExec.scala	Adds createOpTimeMetric and switches the default OP_TIME_NEW metric to use it.
sql-plugin/src/main/scala/com/nvidia/spark/rapids/GpuColumnarToRowExec.scala	Switches OP_TIME_NEW to createOpTimeMetric so companions publish at MODERATE.
sql-plugin/src/main/scala/org/apache/spark/sql/rapids/GpuFileSourceScanExec.scala	Switches scan OP_TIME_NEW to createOpTimeMetric.
sql-plugin/src/main/scala/org/apache/spark/sql/rapids/execution/python/GpuPythonExecBase.scala	Switches Python exec OP_TIME_NEW to createOpTimeMetric.
sql-plugin/src/main/scala/org/apache/spark/sql/rapids/execution/GpuShuffleExchangeExecBase.scala	Switches shuffle read/write op-time metrics to createOpTimeMetric.
sql-plugin/src/main/scala/org/apache/spark/sql/rapids/execution/GpuCustomShuffleReaderExec.scala	Switches shuffle reader op-time metric to createOpTimeMetric.
sql-plugin/src/main/scala/org/apache/spark/sql/rapids/GpuWriteStatsTracker.scala	Uses createOpTime for write stats operatorTime metric so companions publish at MODERATE.
sql-plugin/src/main/scala/org/apache/spark/rapids/hybrid/HybridFileSourceScanExec.scala	Switches hybrid scan OP_TIME_NEW to createOpTimeMetric.
sql-plugin/src/main/scala/com/nvidia/spark/rapids/RapidsConf.scala	Updates metrics-level description to reflect op-time companion availability at MODERATE.
docs/configs.md	Mirrors the updated spark.rapids.sql.metrics.level documentation text.
sql-plugin/src/test/scala/com/nvidia/spark/rapids/GpuMetricFactorySuite.scala	Adds tests for companion publication levels and serialized-accumulator overhead impact.

[binmahone]

build