sparkforensics-server 0.5.2 → 0.8.1

package/public/docs/assets/user-guide_getting-started_ci-and-automation.md.C0pcQoNc.js

@@ -0,0 +1,29 @@
+import{_ as o,o as t,c as a,a5 as s}from"./chunks/framework.DSg0KOwT.js";const u=JSON.parse('{"title":"CI and automation","description":"","frontmatter":{},"headers":[],"relativePath":"user-guide/getting-started/ci-and-automation.md","filePath":"user-guide/getting-started/ci-and-automation.md"}'),i={name:"user-guide/getting-started/ci-and-automation.md"};function d(n,e,c,r,l,h){return t(),a("div",null,[...e[0]||(e[0]=[s(`<h1 id="ci-and-automation" tabindex="-1">CI and automation <a class="header-anchor" href="#ci-and-automation" aria-label="Permalink to &quot;CI and automation&quot;">​</a></h1><p>How to run SparkForensics from a pipeline or script with the <code>analyze</code> CLI: its output formats, the extra data in the JSON report, and gating on several budgets and candidates.</p><p>In a pipeline or a script, use the <code>analyze</code> CLI instead of the browser dashboard. It parses the same event logs and exits non-zero when a run crosses a threshold you set, so it can gate a build:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -p</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> sparkforensics-cli</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> sparkforensics-analyze</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">file</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">dir</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt; [--max-runtime </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ms]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--max-skew </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ratio]</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  [--max-spill </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">gb]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--max-failed-task-rate </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pct]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--min-efficiency </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pct]</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  [--out </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">path]</span></span></code></pre></div><p>Output is JSON by default; <code>--format md</code> writes the Markdown report instead. Budget violations and inconclusive budgets print to stderr as <code>[violation] ...</code> and <code>[inconclusive] ...</code> lines. The exit code is 0 when every budget passes, 1 when one is violated, 3 when none is violated but one is inconclusive, 2 for a usage error (bad flags or arguments, an invalid <code>--thresholds</code> or <code>--budgets</code> file), 4 when the candidate log can&#39;t be read or parsed or its History Server fetch fails, 5 when the <code>--baseline</code> log can&#39;t be read or parsed, and 6 for an internal error, including a failed <code>--export-html</code>. When several of these apply, the worst wins in this order: 6, 5, 4, 1, 3, 0. A usage error exits 2 before any log is read.</p><p><code>--min-efficiency</code> checks busy core time, the share of executor core time that ran tasks (100 minus the dashboard&#39;s Unused core time). It is not the dashboard&#39;s Efficiency tile, which is the share of wall-clock with a stage running, so the two can differ widely on the same run.</p><p>The command ships in the <code>sparkforensics-cli</code> package. To install it once: <code>npm i -g sparkforensics-cli</code>, then run <code>sparkforensics-analyze</code> directly. <code>npx sparkforensics-analyze &lt;file&gt;</code> is a shorter way to run the same command.</p><p>Point it at a single event-log file, or at one run&#39;s <code>eventlog_v2_*</code> rolling-log directory; any other directory is rejected. Output goes to stdout; pass <code>--out &lt;path&gt;</code> to write it to that file instead.</p><p>Pass <code>--export-html &lt;dir&gt;</code> to write a self-contained HTML dashboard for the run into <code>&lt;dir&gt;</code> (which must not already exist or must be empty). Open <code>&lt;dir&gt;/index.html</code> directly in a browser over <code>file://</code>, with no server, to get the same interactive dashboard offline, without the docs links. This makes it easy to archive or share a run. <code>--redact</code> applies to the exported report too. A SQL execution&#39;s per-query settings keep their values only for the Spark SQL tuning keys the findings read; every other value the job set with <code>spark.conf.set</code> (a path, a bucket, a host) is replaced by Spark&#39;s <code>*********(redacted)</code> placeholder.</p><h2 id="machine-readable-fixes-and-costs" tabindex="-1">Machine-readable fixes and costs <a class="header-anchor" href="#machine-readable-fixes-and-costs" aria-label="Permalink to &quot;Machine-readable fixes and costs&quot;">​</a></h2><p>Each row of the JSON report&#39;s <code>findings</code> array carries two fields for a script or tuning loop that acts on the output without reading prose.</p><p><code>remediation</code> is an array of the changes the row&#39;s <code>recommendation</code> names, in structured form. It is empty when the recommendation names no Spark property and no change to the job.</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;remediation&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;kind&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;conf&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;key&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;spark.sql.shuffle.partitions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;direction&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;increase&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;suggested&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">800</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span></code></pre></div><ul><li><code>kind</code> is <code>&quot;conf&quot;</code> (a Spark property) or <code>&quot;code&quot;</code> (a change to the job&#39;s code or data). A consumer that reads <code>key</code> checks <code>kind</code> first.</li><li><code>direction</code> is <code>&quot;increase&quot;</code> or <code>&quot;decrease&quot;</code> (move the current value that way) or <code>&quot;set&quot;</code> (take the <code>suggested</code> value, for a switch or a class name).</li><li>Entries apply together unless the <code>recommendation</code> words them as alternatives (&quot;either ... or&quot;). An idle-capacity finding (<code>utilization</code>, <code>memoryUtilization</code> with <code>variant: &quot;idleCores&quot;</code>) does this with dynamic allocation off or unset: <code>set spark.dynamicAllocation.enabled</code> and <code>decrease spark.executor.instances</code> are alternatives, so apply one. With dynamic allocation on, it lowers <code>spark.dynamicAllocation.maxExecutors</code>, and also <code>spark.dynamicAllocation.minExecutors</code> when the run logs a value above 0.</li><li><code>suggested</code> is the value the detector computed, or <code>null</code> when it computes none. Counts are numbers, switches are booleans, sizes carry a Spark unit suffix (<code>&quot;1024m&quot;</code>).</li></ul><p>A <code>code</code> entry has no <code>key</code>, <code>direction</code> or <code>suggested</code>, only a <code>hint</code>:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;remediation&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [{ </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;kind&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;code&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;hint&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;salt the key or repartition on a better key&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }]</span></span></code></pre></div><p>Skew findings, and straggler findings whose cause is <code>data</code>, carry one when no property can fix them: the stage&#39;s <code>evidence.origin</code> is <code>other</code>, or AQE skew-join handling is on and its <code>evidence.aqeSkew</code> case calls for a change to the job. The <code>hint</code> is the remedy the <code>recommendation</code> gives.</p><p><code>impactEstimate.coreTimeMs</code> is the busy core time the fix removes: the executor task time, in core-milliseconds, next to the <code>wallClock</code> range (elapsed time). It is a <code>{ &quot;low&quot;: ..., &quot;high&quot;: ... }</code> range with <code>low</code> equal to <code>high</code>, or <code>null</code> when the detector measures no such figure: <code>null</code> means unknown, never zero. Only figures read from the log count: GC time, the executor time of retried and discarded speculative attempts, and for skew and straggler findings the task time the fix removes from the slow tasks. These are set even when the log has no executor core data. A finding with only a wall-clock claim has <code>coreTimeMs: null</code>: its elapsed time is not converted to core time. Task run time is used, not <code>executorCpuTime</code>, so Python worker CPU is not missed.</p><p>Findings whose only figure is bytes or memory-time have <code>coreTimeMs: null</code>, as do findings whose core figure rests on an assumed constant: <code>coreLocality</code>&#39;s per-task fetch penalty and the executor-hours or job-hours of <code>autoscalingChurn</code> and <code>jobFailureRate</code>. Their <code>rawWaste</code> is unchanged.</p><p><code>coreTimeMs</code> never includes idle capacity. A finding whose waste is allocated cores that ran no task (<code>utilization</code>, <code>stageShape</code>&#39;s low parallelism and task/stage skew rows) has <code>coreTimeMs: null</code> and keeps its figure in <code>impactEstimate.rawWaste</code> with <code>&quot;idle&quot;: true</code>; every surface labels it &quot;of idle core capacity&quot;, not &quot;of core time&quot;. A stage&#39;s slow tail is counted once: when <code>skew</code> and <code>straggler</code> both flag the same stage, <code>skew</code> carries the removed task time and <code>straggler</code> has <code>null</code>.</p><p>A cost-only figure for task time is printed as core time (&quot;0.2 core-h of task time (modeled)&quot;), never as a duration beside run-time savings, and a modeled one says so. <code>rawWaste</code> keeps its value and unit. Each finding row also carries <code>estimateProvenance</code>, the sentence that says how the estimate was derived and what its model assumes and leaves out, for example &quot;assumes 200 MB/s per executor over 75 executors; counts disk spill only, not memory spill, serialization or GC&quot;. Scripts read the numbers from <code>impactEstimate</code> and <code>evidence</code>, not from these strings.</p><p><code>impactEstimate.idleCoreTimeMs</code> is the idle capacity as a number a script can rank by: the <code>utilization</code> finding&#39;s allocated core time that ran no task, in core-milliseconds, as a <code>{ &quot;low&quot;: ..., &quot;high&quot;: ... }</code> range with <code>low</code> equal to <code>high</code>. It is the run&#39;s allocated core-milliseconds (<code>allocation.coreHours</code>) minus the busy core-milliseconds, never below zero and never above the allocation. It is the same quantity as the finding&#39;s <code>rawWaste</code>, kept apart from <code>coreTimeMs</code>, which is busy time a fix removes. The field is absent on every other finding, and on a <code>utilization</code> finding the log gives no executor cores to allocate. The <code>memoryUtilization</code> finding with <code>variant: &quot;idleCores&quot;</code> is the memory view of the same condition and carries no <code>idleCoreTimeMs</code>.</p><p>A finding on a serial basis whose figure is modeled has no core time either. <code>partitionSizing</code>&#39;s <code>lowShuffleParallelism</code> reports <code>rawWaste</code> in <code>ms</code>: stage wall-clock that more partitions shorten, not task work they remove. It has <code>coreTimeMs: null</code> and is ranked on <code>wallClock</code>, which models the stage with its longest task split evenly across the partition count the stage needs.</p><p>When the effective <code>spark.sql.shuffle.partitions</code> (logged, else Spark&#39;s 200) is already at or above the count a low-parallelism shuffle stage needs, the property is not what limits that stage: the recommendation points at the stage&#39;s own partitioning (<code>repartition(n)</code> or RDD parallelism) and <code>remediation</code> is empty. When AQE coalescing is on and a stage in a SQL execution ran fewer tasks than the property (or than <code>spark.sql.adaptive.coalescePartitions.initialPartitionNum</code>, which replaces it as the starting count when set), AQE merged the partitions and the recommendation points at <code>spark.sql.adaptive.advisoryPartitionSizeInBytes</code> instead. A stage outside any SQL execution is never read as coalesced. <code>shuffle</code> and <code>partitionSizing</code> (<code>lowShuffleParallelism</code>) findings carry <code>evidence.partitions</code> (<code>raise</code>, <code>sufficient</code>, <code>aqeCoalesced</code> or <code>ownPartitioning</code>) for the case.</p><p>A <code>remediation</code> that sets a property to a fixed value (for example <code>spark.sql.adaptive.skewJoin.enabled</code>, <code>spark.speculation</code> or <code>spark.dynamicAllocation.enabled</code>) is left out when the run&#39;s effective conf already has that value. The effective value is, in order, the setting the SQL execution ran with (its <code>modifiedConfigs</code>, for a finding scoped to one execution), the logged property, and Spark&#39;s default for the run&#39;s <code>sparkVersion</code>. A job that calls <code>spark.conf.set</code> is judged against what it set. The defaults come from Spark&#39;s own configuration sources and cover every property a detector reads or suggests: AQE (<code>spark.sql.adaptive.enabled</code> is off before Spark 3.2 and on from 3.2; skew-join and coalescing from 3.0, and the advisory partition size and <code>coalescePartitions.parallelismFirst</code>, on from 3.2), <code>spark.sql.shuffle.partitions</code> (200), <code>spark.sql.autoBroadcastJoinThreshold</code> (10 MB), speculation (the multiplier is 1.5 and the quantile 0.75 before Spark 4.0, 3 and 0.9 from 4.0) and the dynamic-allocation, serializer and event-log switches, and the executor memory overhead factor (from 3.3) and minimum (from 4.0). A default that depends on the cluster (<code>spark.executor.instances</code>, <code>spark.default.parallelism</code>) is not modeled. Spark before 3.0 has no AQE skew-join handling, so a skew finding on such a run suggests no conf. Booleans compare case-insensitively. The recommendation then stops naming that property and points at the remedy left (for example &quot;AQE skew-join handling is already on, so salt the key or repartition on a better key&quot;), so the text and <code>remediation</code> never disagree. The dashboard&#39;s one-line fix for a group of such findings follows the same effective conf.</p><p>Two effective settings change which fix is offered. Skew-join handling counts as already on only when <code>spark.sql.adaptive.enabled</code> is not effectively <code>false</code>; with AQE off (logged, or the default on Spark 3.0 and 3.1), the skew findings suggest setting <code>spark.sql.adaptive.enabled</code> to <code>true</code> instead. When <code>spark.sql.autoBroadcastJoinThreshold</code> is logged <code>-1</code> (auto-broadcast disabled), and under adaptive execution <code>spark.sql.adaptive.autoBroadcastJoinThreshold</code> is unset or <code>-1</code> too, an over-broadcast finding has an empty <code>remediation</code> and points at removing the <code>broadcast()</code> hint.</p><p>Skew-join handling is only suggested for a stage that reads a shuffle in a SQL execution whose plan has a sort-merge or shuffled-hash join. Skew findings carry <code>evidence.origin</code>: <code>shuffleJoin</code> (the conf above applies), <code>inputScan</code> (a stage reading uneven input files: the remediation lowers <code>spark.sql.files.maxPartitionBytes</code>) or <code>other</code> (no conf is suggested; the <code>remediation</code> holds a <code>code</code> entry). A <code>shuffleJoin</code> finding on a run with AQE skew-join handling on also carries <code>evidence.aqeSkew</code>, the reason handling did or did not act on the stage&#39;s join: <code>split</code>, <code>evenReads</code>, <code>belowThreshold</code>, <code>planShape</code>, <code>userRepartition</code>, <code>joinType</code>, <code>extraShuffle</code> or <code>notSplit</code> (see <code>SKEW</code>). The remediation matches the case: a <code>decrease</code> of the skew threshold or factor for <code>belowThreshold</code>, a <code>set</code> of <code>spark.sql.adaptive.forceOptimizeSkewedJoin</code> for <code>extraShuffle</code> from Spark 3.3 (or on a run with no recorded version that logs the property), next to the <code>code</code> entry when a one-sided <code>joinType</code> is also blocked by an extra shuffle, none for <code>split</code> and <code>evenReads</code>, and a <code>code</code> entry otherwise. <code>shufflePartitionSkew</code> carries the same fields but is judged on shuffle-read sizes, so it is only ever <code>shuffleJoin</code> or <code>other</code>. A <code>stageSlowness</code> finding carries <code>evidence.reads</code> (<code>shuffle</code>, <code>input</code> or <code>other</code>) and suggests partition-count changes only for <code>shuffle</code>; <code>spill</code> and <code>tinyTask</code> carry the same <code>reads</code> key and gate their partition-count advice the same way. On a <code>shuffle</code> stage the remediation names the lever that sized it: <code>spark.sql.shuffle.partitions</code>, AQE&#39;s advisory size or <code>parallelismFirst</code> where AQE coalesced the stage (<code>parallelismFirst=false</code> comes first while it is on, the advisory size after it), or a <code>code</code> entry where the stage&#39;s own <code>repartition(n)</code> or RDD parallelism did. <code>straggler</code> carries <code>evidence.origin</code> and the same skew advice as a skew finding on that stage when its <code>evidence.cause</code> is <code>data</code>; <code>unattributed</code> gets no fix, and other causes get advice for that cause. <code>coldStart</code> and <code>autoscalingChurn</code> carry <code>evidence.dynamicAllocation</code> (<code>on</code> or <code>off</code>) and suggest no dynamic-allocation property when it is <code>off</code>. <code>underBroadcast</code> and <code>overBroadcast</code> carry <code>evidence.broadcastThreshold</code> (<code>limits</code>, <code>notLimiting</code> or <code>disabled</code>) and suggest changing the threshold only when it limits the join.</p><p>The CLI also supports fetching a run directly from a reachable Spark History Server (<code>--shs-base-url</code>/<code>--app-id</code>/<code>--attempt-id</code>) instead of a local file, comparing a candidate run against a baseline with regression gating (<code>--baseline</code>/<code>--max-regression-pct</code>/<code>--regression-metric</code>/ <code>--fail-on-introduced</code>; the baseline is a local file or rolling-log directory, or a History Server run through <code>--baseline-shs-base-url</code>, see <a href="#baseline-from-a-history-server">Baseline from a History Server</a>), several regression budgets and several candidates in one call (<code>--regression-budget</code>/<code>--budgets</code>, see <a href="#several-budgets-and-several-candidates">Several budgets and several candidates</a>), rewriting run-specific text before stages are paired (<code>--normalize-path</code>, see <a href="#pairing-stages-across-runs">Pairing stages across runs</a>), leaving per-run configuration keys out of the comparison (<code>--ignore-conf</code>, see <a href="#comparing-configuration-and-capacity">Comparing configuration and capacity</a>), redacting the app id, the app name and any host/IP tokens before sharing output (<code>--redact</code>), and narrowing the findings to certain impact bands, types, or a stage (<code>--impact</code>/<code>--type</code>/<code>--stage</code>), and tuning detector thresholds from a file (<code>--thresholds</code>, below). Run it with <code>--help</code> for the full flag list.</p><p>Same caveat as above: if the History Server is only reachable through an SSH bastion, <code>--shs-base-url</code> can&#39;t reach it either: see <a href="./../alternative-log-retrieval/ssh-bastion.html#behind-an-ssh-bastion">Behind an SSH bastion</a>.</p><p>Running in Airflow instead of a plain CI pipeline? See <a href="https://github.com/shuffle-works/sparkforensics-operator" target="_blank" rel="noreferrer">sparkforensics-operator</a>, an Airflow operator that wraps the CLI and acts on the result after each Spark job, so you don&#39;t have to wire up the call yourself.</p><p>Want an AI assistant to diagnose a run directly, without the dashboard or a CI gate? See <a href="./../mcp-tools.html">MCP tools reference</a>.</p><h2 id="write-targets" tabindex="-1">Write targets <a class="header-anchor" href="#write-targets" aria-label="Permalink to &quot;Write targets {#write-targets}&quot;">​</a></h2><p>The JSON report has a top-level <code>writeTargets</code> object listing every SQL write in the run, so a script can check where a job wrote without reading the plan. It has no Markdown counterpart. The MCP <code>diagnose_run</code> tool returns it too.</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;writes&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    {</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;sqlExecutionId&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">3</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;nodeId&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;e3:n0&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;command&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;InsertIntoHadoopFsRelationCommand&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;recognized&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;kind&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;path&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;target&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;hdfs://nn/sandbox/out/t1&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;outputRows&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">5000000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;outputRowsSource&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;nodeMetric&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;outputBytes&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">24824981</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;mergeRows&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;raw&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Execute InsertIntoHadoopFsRelationCommand hdfs://nn/sandbox/out/t1, false, Parquet, ...&quot;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ],</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;executionsWithoutPlan&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [{ </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;sqlExecutionId&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">4</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;reason&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;noPlan&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }],</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;skippedLines&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><ul><li><p><code>writes</code> holds one row per write node, ordered by SQL execution id and then by position in the plan. A <code>DeltaTable</code> API merge has no write node: it is one extra row per merge, see <a href="#delta-writes">Delta writes</a>. <code>command</code> is the plan node&#39;s name without the <code>Execute </code> prefix or an <code>Exec</code> suffix, <code>nodeId</code> is the plan node&#39;s id, and <code>raw</code> is the node&#39;s full plan string as the log recorded it.</p></li><li><p><code>kind</code> says how to read <code>target</code>:</p><ul><li><code>path</code> is a filesystem location.</li><li><code>table</code> is a table name whose catalog the command states or implies: a Hive or V1 command&#39;s <code>database.table</code>, a DataSource V2 name with a catalog part (<code>catalog.namespace.table</code>), or a Delta command&#39;s table as <code>database.table</code> (a table in the session catalog) or <code>catalog.database.table</code>.</li><li><code>unqualifiedTable</code> is a DataSource V2 name with no catalog part, such as <code>default.events</code> or <code>events</code>. The log does not say which catalog it lives in, so a check on its database part alone can match the wrong catalog.</li><li><code>jdbcTable</code> is a <code>dbtable</code> of a JDBC write. It names a table in an external database, not in a Spark catalog, and the database itself (the JDBC url) is not reported.</li></ul><p>Every target is copied verbatim from the plan string: nothing is resolved, so a relative path, an unexpanded <code>\${var}</code> placeholder or a bare table name appears exactly as the log states it. Backticks around table name parts are dropped.</p></li><li><p><code>target</code> and <code>kind</code> are <code>null</code> when the target cannot be determined. That covers a node whose plan string has no target (Spark omits it for some commands, and Delta command nodes carry none on real logs, which <a href="#delta-writes">Delta writes</a> covers), a redacted option value, a plan string that names more than one candidate target, and a plan string Spark cut short. A target is reported only when its whole text is followed by a delimiter in the plan string: a path cut by <code>spark.sql.maxMetadataStringLength</code> or a name with a <code>...</code> marker in it is <code>null</code>, never a partial path. A trailing <code>... N more fields</code> after the target, such as the column list of <code>InsertIntoHadoopFsRelationCommand</code>, does not affect the target before it. Treat a <code>null</code> target as unknown, not as inside or outside any location.</p></li><li><p><code>outputRows</code> is the number of rows the write stored. It is the node&#39;s own <code>number of output rows</code> SQL metric when the log has one. Otherwise, for a plain write, it is the sum of <code>outputRecords</code> over the stages of the write&#39;s root execution: a Delta DataFrame write node carries no metric, and its stages run in a child execution of the node&#39;s own. A plain write is any write except MERGE, UPDATE, DELETE, table maintenance and the <code>DeltaMerge</code> row. The sum applies only when the root execution holds one logical write: plain writes that name the same table or path (a CTAS or RTAS and the append it runs) count once and share the figure. For a Delta MERGE, UPDATE or DELETE it is the number of rows written to new files, read from the command node&#39;s counters: for a MERGE the inserted, updated and copied rows (<code>mergeRows.inserted + mergeRows.updated + mergeRows.copied</code>), for an UPDATE <code>number of rows touched (copied + updated)</code>, and for a DELETE the target rows it copied. Rows a DELETE or a MERGE delete clause removes are not written, so they are not output rows. <code>null</code> means unknown, and a write that stored nothing is <code>0</code>. A plain write left with <code>null</code> is listed in <code>notRunChecks</code> as <code>writeOutputRows</code>.</p></li><li><p><code>outputRowsSource</code> says where <code>outputRows</code> came from: <code>nodeMetric</code>, <code>stageSum</code>, <code>commandMetric</code> (the row counters of a MERGE, UPDATE or DELETE node), or <code>null</code> when <code>outputRows</code> is <code>null</code>. Compare two runs&#39; row counts only when both sides name the same source.</p></li><li><p><code>outputBytes</code> is the number of bytes written to new files. For a plain write it is the sum of the bytes written by the same stages, under the same rule as the stage sum of rows. For a MERGE it is the node&#39;s <code>number of target bytes added</code>, and for an UPDATE or DELETE its <code>number of bytes added</code> (<code>0</code> for a DELETE that rewrote no file). It is <code>null</code> when no such figure is available.</p></li><li><p><code>mergeRows</code> holds the row counts of a Delta MERGE: <code>inserted</code>, <code>updated</code>, <code>deleted</code> and <code>copied</code>, read from the <code>MergeIntoCommand</code> node&#39;s SQL metrics (<code>number of inserted rows</code>, <code>number of updated rows</code>, <code>number of deleted rows</code> and <code>number of target rows rewritten unmodified</code>; older Delta releases name the last one <code>number of rows copied</code>). It is <code>null</code> for every other command, for a MERGE node that reports none of the four, and for a <code>DeltaMerge</code> row (see <a href="#delta-writes">Delta writes</a>). To check that two runs merged the same rows, compare <code>inserted + updated + deleted</code>. <code>copied</code> counts target rows Delta rewrote unchanged, which depends on how the table&#39;s files are laid out.</p></li><li><p><code>recognized</code> is <code>true</code> for the commands below and <code>false</code> for a write-like node that is not in that list. An unrecognized write always has <code>target</code> and <code>kind</code> <code>null</code>, and <code>raw</code> is the only information about it.</p></li><li><p><code>executionsWithoutPlan</code> lists the SQL executions whose writes the report cannot see, each with a <code>reason</code>. <code>noPlan</code> means the execution started but the log has no plan for it, such as an execution still running when the log was cut off (a plan is read when its execution ends). <code>unreadableStart</code> means the execution&#39;s start event was skipped because it could not be read, for example a plan nested deeper than 500 nodes or a start line cut off at the end of the log. A write in one of these executions is not in <code>writes</code>, so a non-empty list means the report may be incomplete.</p></li><li><p><code>skippedLines</code> is the number of log lines the parser could not read. A line cut off before its execution id is not in <code>executionsWithoutPlan</code>, so a non-zero count means a write may be missing even when that list is empty. It is <code>null</code> when the count is unknown.</p></li></ul><p>Recognized commands and where their target comes from:</p><table tabindex="0"><thead><tr><th>Command</th><th>Target</th></tr></thead><tbody><tr><td><code>InsertIntoHadoopFsRelationCommand</code></td><td><code>path</code>: the first argument, including for an <code>INSERT OVERWRITE ... PARTITION</code> that prints a static-partition map after it</td></tr><tr><td><code>InsertIntoHiveTable</code>, <code>CreateDataSourceTableAsSelectCommand</code>, <code>CreateHiveTableAsSelectCommand</code>, <code>OptimizedCreateHiveTableAsSelectCommand</code></td><td><code>table</code>: the first argument</td></tr><tr><td><code>SaveIntoDataSourceCommand</code></td><td><code>path</code> from the <code>path</code> option, or <code>jdbcTable</code> from the JDBC <code>dbtable</code>/<code>table</code> option</td></tr><tr><td><code>AppendData</code>, <code>OverwriteByExpression</code>, <code>OverwritePartitionsDynamic</code>, <code>ReplaceData</code>, <code>WriteDelta</code>, <code>WriteToDataSourceV2</code>, <code>AppendDataExecV1</code>, <code>OverwriteByExpressionExecV1</code></td><td><code>table</code> or <code>unqualifiedTable</code>: the <code>table=</code> of the connector&#39;s write object, for example Iceberg&#39;s <code>IcebergWrite(table=..., ...)</code>. For a Delta table, see <a href="#delta-writes">Delta writes</a></td></tr><tr><td><code>CreateTableAsSelect</code>, <code>AtomicCreateTableAsSelect</code>, <code>ReplaceTableAsSelect</code>, <code>AtomicReplaceTableAsSelect</code></td><td><code>table</code> or <code>unqualifiedTable</code>: the identifier after the catalog object, which does not name the catalog</td></tr><tr><td><code>WriteIntoDelta</code>, <code>WriteIntoDeltaCommand</code>, <code>UpdateCommand</code>, <code>DeleteCommand</code>, <code>MergeIntoCommand</code></td><td><code>path</code>: the first argument when it is a <code>delta.</code> path table (never for <code>MergeIntoCommand</code>, whose plan string also prints the source); otherwise as in <a href="#delta-writes">Delta writes</a></td></tr><tr><td><code>CreateDeltaTableCommand</code>, <code>OptimizeTableCommand</code>, <code>RestoreTableCommand</code>, <code>DeltaReorgTableCommand</code></td><td><code>path</code>: the first argument when it is a <code>delta.</code> path table, otherwise <code>null</code></td></tr><tr><td><code>DeltaMerge</code></td><td>not a plan node: one row per <code>DeltaTable</code> API merge, see <a href="#delta-writes">Delta writes</a></td></tr></tbody></table><p>A plan node not in the table is a write when its operator name (the first word of the node name after any leading <code>Execute</code>, so not the relation or table a scan prints after it), split into CamelCase words, contains <code>Write</code>, <code>Insert</code>, <code>Save</code>, <code>Overwrite</code>, <code>Append</code>, <code>Merge</code>, <code>Update</code>, <code>Delete</code>, <code>Truncate</code>, <code>Replace</code>, <code>Drop</code>, <code>Load</code>, <code>Vacuum</code>, <code>Convert</code>, <code>Clone</code>, <code>Restore</code>, <code>Optimize</code>, <code>Alter</code>, <code>Reorg</code>, <code>Rename</code> or <code>Call</code>, or contains <code>TableAsSelect</code>, <code>AddPartition</code>, <code>DropPartition</code>, <code>RenamePartition</code> or <code>RecoverPartitions</code>. That covers table DDL and <code>ADD PARTITION ... LOCATION</code>, and an Iceberg procedure call (<code>Call</code>), whose target is a procedure argument and not a path, so it is reported with a <code>null</code> target. A name containing <code>Join</code> (<code>SortMergeJoin</code>) and these operators that share a word with a write but write nothing are not: <code>WriteFiles</code> (the child of a write command), <code>AppendColumns</code>, <code>AppendColumnsWithObject</code>, <code>MergeRows</code>, <code>StateStoreSave</code>, <code>StateStoreRestore</code>, <code>SessionWindowStateStoreSave</code>, <code>SessionWindowStateStoreRestore</code> and <code>UpdateEventTimeWatermarkColumn</code>. The classification leans toward reporting too much: a node that matches by name is listed with a <code>null</code> target rather than dropped.</p><h3 id="delta-writes" tabindex="-1">Delta writes <a class="header-anchor" href="#delta-writes" aria-label="Permalink to &quot;Delta writes {#delta-writes}&quot;">​</a></h3><p>On a real log a Delta command node (<code>MergeIntoCommand</code>, <code>UpdateCommand</code>, <code>DeleteCommand</code>, <code>WriteIntoDelta</code>, <code>SaveIntoDataSourceCommand</code>) is a bare name: its plan string has no target. The target is read from up to two other places, in this order, and is <code>null</code> when neither names exactly one target.</p><ol><li>The command&#39;s <code>Arguments:</code> line in Spark&#39;s physical plan description. The parser drops the rest of that text to save memory, but keeps this one line for these commands. A quoted table name that appears once on the line is the target, as <code>kind: &quot;table&quot;</code> (<code>spark_catalog</code> is dropped, so it reads <code>database.table</code>). A <code>SaveIntoDataSourceCommand</code> is read this way only when the line shows a Delta source, and its target is the <code>path</code> option. A description that spans two read chunks is not kept for a <code>SaveIntoDataSourceCommand</code>, which prints its whole query plan under it; its target is then <code>null</code>.</li><li>For <code>MergeIntoCommand</code>, <code>UpdateCommand</code> and <code>DeleteCommand</code> only, the <code>_delta_log</code> path in the plans of the executions that share the command&#39;s root execution, as <code>kind: &quot;path&quot;</code>. Exactly one distinct path must appear. It applies only when the command is its own root execution, and a source that is itself a Delta table adds a second path and leaves the target <code>null</code>. The write commands (<code>WriteIntoDelta</code>, <code>WriteIntoDeltaCommand</code>, <code>SaveIntoDataSourceCommand</code>) never take this step, because a write may read another Delta table as its source: with no table or <code>path</code> option on the arguments line, their target is <code>null</code>.</li></ol><p>An append or overwrite of an existing Delta table (<code>saveAsTable</code> in <code>append</code> or <code>overwrite</code> mode on an existing table, <code>INSERT INTO</code>, <code>INSERT OVERWRITE</code>) prints the table object as its first argument, and that names the table: <code>kind: &quot;table&quot;</code> as <code>database.table</code> (<code>catalog.database.table</code> outside the session catalog), or <code>kind: &quot;path&quot;</code> for a path-based table. A <code>CREATE TABLE ... AS SELECT</code>, <code>CREATE OR REPLACE TABLE</code> or <code>saveAsTable</code> that creates or replaces a table runs two executions under one root: the create or replace node, which names the table as <code>unqualifiedTable</code> because Delta&#39;s catalog object does not state its catalog name, and an <code>AppendDataExecV1</code> whose staged table has no name. That append takes the table its root&#39;s create or replace node names, and is <code>null</code> when the root has no single such node.</p><p>A merge made with <code>DeltaTable.merge(...).execute()</code> normally runs a <code>MergeIntoCommand</code> too (its description is <code>toDataset$ at DeltaMergeBuilder</code>), and is reported like a SQL MERGE, including two merges run from threads of one session, whose sub-queries are told apart by their root execution. Some logs have no such command execution for an API merge. Its queries are then separate root executions, and the only things tying them together are a <code>MERGE operation</code> description and adjacent execution ids. Each run of consecutive ids with such a description is reported as one write with the synthetic command <code>DeltaMerge</code>, <code>kind: &quot;path&quot;</code> and the table path from the <code>_delta_log</code> of the plans in the run. The log holds no table name for these merges. The run must hold a write phase (a description containing <code>writing</code> or <code>rewriting</code>), because a run that only scanned may have read the merge&#39;s source. The target is <code>null</code> when the run has no write phase, names zero or several paths, has a plan or start time missing, or has start times that overlap another run&#39;s (merges on concurrent threads); <code>raw</code> says which. Two merges whose executions have consecutive ids are one run and name two paths, so they get no target. A description a user sets that starts with <code>MERGE operation</code> is indistinguishable from Delta&#39;s and is reported the same way. <code>raw</code> reads <code>Delta MERGE operation, executions 10-17</code>.</p><p>Only SQL writes are covered. Writes made outside Spark SQL, such as an RDD <code>saveAsTextFile</code> or a direct filesystem call from the driver, do not appear in the event log and are not in <code>writeTargets</code>.</p><h2 id="generator" tabindex="-1">Generator <a class="header-anchor" href="#generator" aria-label="Permalink to &quot;Generator&quot;">​</a></h2><p>The CLI&#39;s JSON output carries a <code>generator</code> block naming the build that wrote it: <code>name</code> and <code>version</code> of the CLI package, and <code>buildId</code>, the build id of the analysis core the CLI loaded. Equal build ids mean equal analysis code. With <code>--baseline</code> the block is inside <code>candidate</code> and also leads <code>comparison</code>. The MCP <code>diagnose_run</code> and <code>compare_runs</code> tools return the same block with the <code>sparkforensics-mcp</code> package name and version. The block holds no run identifiers, so <code>--redact</code> leaves it as is.</p><p>An <code>app</code> block next to it names the Spark application the report describes: <code>id</code> and <code>attemptId</code>, which is <code>null</code> when the log has none (only a cluster-mode run writes one). Under <code>--redact</code> the id is pseudonymized. A comparison names both runs in <code>baselineApp</code> and <code>candidateApp</code>.</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;generator&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;name&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;sparkforensics-cli&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;version&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;0.7.0&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;buildId&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;9c1f3a7e2b4d&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span></code></pre></div><h2 id="metrics-block" tabindex="-1">Metrics block <a class="header-anchor" href="#metrics-block" aria-label="Permalink to &quot;Metrics block&quot;">​</a></h2><p>The CLI&#39;s JSON output carries a <code>metrics</code> block next to the report, for scripts that act on a run without reading the report. With <code>--baseline</code> it is inside <code>candidate</code>. The MCP <code>diagnose_run</code> tool returns the same block. It has its own <code>schemaVersion</code>, separate from the report&#39;s. A figure the log cannot provide is <code>null</code>, never <code>0</code>: a log from a Spark version that records no CPU time has <code>executorCpuTimeMs: null</code>, and a log cut off before any executor joined has null allocation. The time, data and task figures, run-level and per row, include the work of every attempt of a resubmitted stage, failed attempts too, and the tasks of a failed attempt that end after it (killed or still running when it failed); skew describes the latest attempt.</p><table tabindex="0"><thead><tr><th>Field</th><th>Meaning</th></tr></thead><tbody><tr><td><code>runComplete</code></td><td><code>true</code> when the log has an application-end record. <code>false</code> means the log was cut off and every total covers only what it recorded.</td></tr><tr><td><code>time.wallClockMs</code></td><td>Application start to end; null without both.</td></tr><tr><td><code>time.executorCpuTimeMs</code></td><td>Summed CPU time of every task attempt, including failed attempts, retries and speculative copies that lost. Null when no task recorded any. Misses Python worker CPU, see <code>python</code>.</td></tr><tr><td><code>time.executorRunTimeMs</code>, <code>time.gcTimeMs</code></td><td>Summed run time and JVM GC time of every task attempt, counted like the CPU time.</td></tr><tr><td><code>data.memorySpillBytes</code>, <code>data.diskSpillBytes</code></td><td>Summed spill.</td></tr><tr><td><code>data.shuffleReadBytes</code>, <code>data.shuffleWriteBytes</code></td><td>Summed shuffle bytes, local plus remote on the read side.</td></tr><tr><td><code>data.inputBytes</code>, <code>data.outputBytes</code>, <code>data.outputRows</code></td><td>Summed input, output and rows written. <code>outputRows</code> is null when no task reported rows.</td></tr><tr><td><code>data.peakExecutionMemoryBytes</code></td><td>The largest per-task peak execution memory. Null when every task reports 0.</td></tr><tr><td><code>shape.taskCount</code>, <code>shape.stageCount</code></td><td>Distinct task records and stages.</td></tr><tr><td><code>shape.failedStageAttempts</code></td><td>Stage attempts that ended with a failure reason, including an attempt Spark then resubmitted (a fetch failure, for example).</td></tr><tr><td><code>shape.retriedStages</code></td><td>Stages submitted more than once.</td></tr><tr><td><code>shape.failedTasks</code>, <code>shape.retriedTasks</code></td><td>Task-level counts: tasks whose final attempt failed, and task attempts superseded by a retry.</td></tr><tr><td><code>shape.maxSkew</code></td><td>The largest stage skew ratio, the figure <code>--max-skew</code> checks (P95 over median, or max over median for a stage with few tasks; <code>skew.minTasksForP95</code> from <code>--thresholds</code> applies).</td></tr><tr><td><code>allocation.coreHours</code>, <code>allocation.memoryGbHours</code></td><td>See <a href="#allocation">Allocation</a>.</td></tr><tr><td><code>allocation.dynamicAllocation</code>, <code>allocation.executorsPeak</code>, <code>allocation.executorsMean</code>, <code>allocation.executorCores</code>, <code>allocation.executorSeconds</code></td><td>The executor allocation behind the hours, see <a href="#allocation">Allocation</a>.</td></tr><tr><td><code>python.shareOfTaskRunTime</code></td><td>See <a href="#python-share">Python share</a>.</td></tr><tr><td><code>stages</code></td><td>The per-stage rows.</td></tr></tbody></table><p><code>stages</code> holds one row per stage fingerprint, keyed by the same fingerprint the run comparison matches stages on (the normalized stage name plus the stage&#39;s plan nodes), so the same stage has the same key in a baseline and a candidate run. A stage repeated in a loop shares one key: its row sums the repeats and lists them in <code>stageIds</code>. A row carries <code>durationMs</code>, <code>executorCpuTimeMs</code>, <code>executorRunTimeMs</code>, <code>gcTimeMs</code>, the spill, shuffle, input and output figures, <code>outputRows</code>, <code>peakExecutionMemoryBytes</code>, <code>taskCount</code>, <code>failedTasks</code>, <code>retriedTasks</code> and <code>skew</code> (the largest skew ratio among the repeats) as above, plus <code>failed</code> (an attempt of the stage failed), <code>retried</code> (the stage was submitted more than once) and <code>python</code> flags. The stage-attempt figures, run-level and per row, are null for a stage record that carries no attempt count. With <code>--redact</code> the <code>metrics</code> and <code>effectiveConf</code> blocks are built from the redacted run the report uses, so they carry the same <code>host-N</code> and <code>app-N</code> pseudonyms: the keys come from redacted stage names.</p><h3 id="allocation" tabindex="-1">Allocation <a class="header-anchor" href="#allocation" aria-label="Permalink to &quot;Allocation&quot;">​</a></h3><p><code>allocation.coreHours</code> is the sum over executors of cores times hours alive. <code>allocation.memoryGbHours</code> is the sum of memory times hours alive, in GiB (1024 MiB). An executor is alive from its executor-added event to its first later executor-removed event. One with no removal event closes at the application end when the log has one. In a cut-off log (<code>runComplete</code> false) it closes at the last timestamp the log records (the latest application, stage or executor event), so the figure is a lower bound.</p><p>Cores per executor are the executor-added event&#39;s total cores. Under dynamic allocation or YARN defaults, where <code>spark.executor.cores</code> is not set, that is the core count the cluster manager actually granted; when the event carries none, <code>spark.executor.cores</code> is used. If neither exists the core-hours are null.</p><p>Memory per executor is the container size Spark requests: <code>spark.executor.memory</code> (1g when unset), plus the overhead, plus <code>spark.memory.offHeap.size</code> when <code>spark.memory.offHeap.enabled</code> is <code>true</code>, plus <code>spark.executor.pyspark.memory</code>. The overhead is <code>spark.executor.memoryOverhead</code>, else the legacy <code>spark.yarn.executor.memoryOverhead</code>, else the larger of 384 MiB and <code>spark.executor.memoryOverheadFactor</code> (default 0.1) times the executor memory. Memory GB-hours are null when the log records no Spark properties at all, or a memory property cannot be read. Driver resources are not included.</p><p>The same alive intervals give the executor figures, each null when the log has no executor-added event:</p><ul><li><code>allocation.executorSeconds</code> is the sum of seconds alive over executors.</li><li><code>allocation.executorsPeak</code> is the largest number of executors alive at once.</li><li><code>allocation.executorsMean</code> is <code>executorSeconds</code> divided by the seconds from application start to close (the end, or the last recorded timestamp in a cut-off log), so the mean times the run&#39;s wall clock is <code>executorSeconds</code>. It is null when the log has no application start.</li><li><code>allocation.executorCores</code> is the cores per executor when every executor has the same count, null when a count is unknown or they differ.</li></ul><p><code>allocation.dynamicAllocation</code> is <code>on</code> or <code>off</code> when the log records <code>spark.dynamicAllocation.enabled</code>, and <code>null</code> when it does not. Spark&#39;s default is off, but a key the log never recorded is not reported as off. It is read whether or not the log has executor events. The <code>coldStart</code> and <code>autoscalingChurn</code> findings&#39; <code>evidence.dynamicAllocation</code> reports <code>on</code> for any run not logged as off.</p><h3 id="python-share" tabindex="-1">Python share <a class="header-anchor" href="#python-share" aria-label="Permalink to &quot;Python share&quot;">​</a></h3><p><code>python.shareOfTaskRunTime</code> is the summed task run time of Python stages divided by the summed task run time of all stages; null when no task run time was recorded. It is <code>0</code> for a run with task time and no Python stage. Executor CPU time counts only the JVM task thread, so on a run with a high share it misses the CPU of the Python worker processes; treat <code>executorCpuTimeMs</code> as unreliable there.</p><p>A stage is a Python stage when either signal holds:</p><ul><li>a plan node attributed to it is a Python operator (<code>PythonRDD</code>, <code>BatchEvalPython</code>, <code>ArrowEvalPython</code>, <code>PythonMapInArrow</code>, or a pandas/Arrow grouped or map operator such as <code>FlatMapGroupsInPandas</code>, including suffixed variants such as <code>BatchEvalPythonUDTF</code> and <code>FlatMapGroupsInPandasWithState</code> and the Spark 4.1 <code>ArrowAggregatePython</code> and <code>ArrowWindowPython</code>), which catches Python UDFs and UDTFs inside SQL;</li><li>its name or call site names <code>PythonRDD</code> or <code>org.apache.spark.api.python</code>, which catches RDD lambdas that have no plan and stages that cannot be matched to one.</li></ul><p>The &quot;tasks mostly idle&quot; check that keeps a low-CPU stage from being treated as waiting on an external system uses the same test.</p><h3 id="other-surfaces" tabindex="-1">Other surfaces <a class="header-anchor" href="#other-surfaces" aria-label="Permalink to &quot;Other surfaces&quot;">​</a></h3><p>Every figure the metrics block shares with another surface reads the same core code as that surface. The run comparison (the dashboard&#39;s comparison view, the CLI&#39;s <code>--baseline</code> and the MCP <code>compare_runs</code> tool) uses the same sums for run time, CPU time, GC time, spill, input, output and task count, so a comparison metric equals the matching <code>metrics</code> field for the same run, including the work of failed and speculative task attempts. Per-stage views in the dashboard (the stage table and stage detail) describe the stage&#39;s latest attempt and the task attempts that won, so a stage&#39;s own figures can be smaller than its row in <code>metrics.stages</code>. The dashboard&#39;s Unused core time, the <code>utilization</code> finding&#39;s percentage and its idle figure all measure against available capacity, which is <code>allocation.coreHours</code> (cores times the hours each executor was alive), so under dynamic allocation a run is never idle for cores it did not hold. The utilization finding&#39;s <code>cpuUtilizationPct</code> is a share of that capacity, and is null, as <code>time.executorCpuTimeMs</code> is, when the log recorded no CPU time.</p><h2 id="effective-conf" tabindex="-1">Effective conf <a class="header-anchor" href="#effective-conf" aria-label="Permalink to &quot;Effective conf&quot;">​</a></h2><p>The JSON output also carries <code>effectiveConf</code> (with its own <code>schemaVersion</code>), the Spark properties the run started with, so a script can check that a <code>--conf</code> overlay took effect. It is null when the log records no Spark properties. With <code>--baseline</code> it is inside <code>candidate</code>. The MCP <code>diagnose_run</code> tool returns the same block.</p><ul><li><code>values</code>: property to value, for every property that is not withheld.</li><li><code>maskedKeys</code>: properties present in the log whose value is withheld.</li><li><code>absentKeys</code>: with <code>--conf-keys</code>, the requested properties the log does not contain.</li></ul><p>A value is withheld when its key or value matches Spark&#39;s default secret pattern (<code>(?i)secret|password|token|access[.]?key</code>), as Spark&#39;s own redaction does, when its key names another credential form (<code>passwd</code>, <code>pwd</code>, <code>pass</code>, <code>apiKey</code>, <code>accountKey</code> as in <code>fs.azure.account.key.*</code>, <code>privateKey</code>, <code>sas</code>, <code>sig</code>, <code>credential</code>), when the key or value matches the job&#39;s own <code>spark.redaction.regex</code> (when the log records one; if that pattern uses syntax JavaScript cannot evaluate, every value is withheld), or when the key or value matches <code>--conf-redact-regex &lt;pattern&gt;</code>. A withheld property shows that it is present, not what it is set to, so the output cannot tell you whether a masked property has the value you expected. No hash or other derivative of a withheld value is emitted.</p><p>In every other value, credentials are replaced with <code>[redacted]</code>: in a value that looks like a URL, <code>user:password@host</code> userinfo and the Oracle thin <code>user/password@host</code> form; in any value, <code>name=value</code> parameters named <code>password</code>, <code>passwd</code>, <code>pwd</code>, <code>pass</code>, <code>apikey</code>, <code>accountkey</code>, <code>sas</code>, <code>sig</code>, <code>signature</code> and similar (JDBC and ODBC strings, query strings, JVM options), including signature parameters such as Azure SAS <code>sig=</code> and <code>X-Amz-Signature=</code>. <code>--conf-keys a,b</code> narrows <code>values</code> and <code>maskedKeys</code> to the named properties.</p><p>With <code>--redact</code>, the host names the report pseudonymizes become <code>host-N</code> in every value: the values of <code>*.host</code> and <code>*.hostname</code> properties, executor hosts, and IP or EC2-style addresses. <code>spark.app.name</code> becomes the application&#39;s <code>app-N</code> pseudonym. A host name that appears only in some other property is left as is. The properties known to carry real host names this way are <code>spark.master</code>, <code>spark.yarn.historyServer.address</code> and the YARN proxy and HA keys ending in <code>AmIpFilter.param.PROXY_HOSTS</code> and <code>RM_HA_URLS</code>. Withhold them with <code>--conf-redact-regex</code> or leave them out with <code>--conf-keys</code>.</p><h2 id="pairing-stages-across-runs" tabindex="-1">Pairing stages across runs <a class="header-anchor" href="#pairing-stages-across-runs" aria-label="Permalink to &quot;Pairing stages across runs {#pairing-stages-across-runs}&quot;">​</a></h2><p>With <code>--baseline</code>, the <code>comparison</code> object pairs the stages of the two runs (<code>stagePairs</code>, with each pair&#39;s <code>deltas</code>) and reports <code>runtimeCoverage</code>, the share of both runs&#39; executor run time that sits in paired or replanned stages. <code>confidence</code> is <code>ok</code>, <code>low</code> or <code>insufficient</code>: <code>low</code> when the application names differ or <code>runtimeCoverage</code> is under 0.9, <code>insufficient</code> when neither run recorded any executor run time. <code>confidence</code> does not change an exit code. The fields and the matching rules are in <a href="./../mcp-tools/compare-runs.html"><code>compare_runs</code></a> and <a href="./../run-comparison/how-stages-are-matched.html">How stages are matched</a>.</p><p>When a stage writes to a path that differs per run, for example <code>{sandbox_root}/{session}/{variant}/{batch}</code> where the variant is <code>baseline</code> in one run and <code>c07b</code> in the other, the write stage cannot pair, and it is often the heaviest. Pass <code>--normalize-path &lt;regex&gt;</code>, repeatable, to rewrite what the patterns match, in every plan node&#39;s text, before stages are paired:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sparkforensics-analyze</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> candidate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --baseline</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> baseline</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --normalize-path</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;/sandbox/[^/]+/[^/]+/&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --format</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> json</span></span></code></pre></div><p>Every match is replaced with a fixed token. Despite the name it is a generic regular expression, not only for paths. It needs a baseline and applies to every candidate of a several-candidates run. It changes which stages pair, and so <code>stagePairs</code>, <code>runtimeCoverage</code> and <code>confidence</code>; findings and the other metrics are untouched. At most 16 patterns of 200 characters each. An invalid pattern, or one that matches the empty string, exits <code>2</code> before any log is read.</p><h3 id="comparing-configuration-and-capacity" tabindex="-1">Comparing configuration and capacity <a class="header-anchor" href="#comparing-configuration-and-capacity" aria-label="Permalink to &quot;Comparing configuration and capacity&quot;">​</a></h3><p><code>comparison.comparability</code> states what the two runs share, so a time difference that comes from capacity is not read as a regression. It holds the Spark configuration keys whose values differ (<code>conf</code>), whether every stage pairs (<code>plan</code>), input bytes, output rows and output bytes of both runs (<code>volume</code>), the mean and peak executors (<code>capacity</code>), the overlap of the two run windows (<code>overlapMs</code>) and the factors that bridge the wall-clock difference (<code>wallClockBridge</code>). When the configuration, plan and output agree, <code>comparison.verdict.tone</code> is <code>equivalent</code>, and its title names where the time went. When the wall clock and executor run-time or allocated core-hours move opposite ways, the tone is <code>mixed</code>.</p><p>Pass <code>--ignore-conf &lt;regex&gt;</code>, repeatable, for configuration keys that differ by design, such as a per-run output path. A key that matches is left out of <code>conf.differences</code> and listed in <code>conf.ignoredKeys</code>. The application id, start time and driver address are always left out. With a baseline, a property withheld from <code>effectiveConf</code> (including by <code>--conf-redact-regex</code>) is also withheld from the comparison: it is listed in <code>conf.withheldKeys</code> and never compared. Limits and errors are those of <code>--normalize-path</code>. Pass <code>--noise-band-pct &lt;pct&gt;</code> (default <code>2</code>) to set the share of the baseline value under which a metric row reads <code>withinNoise: true</code>; the flag never changes a row&#39;s <code>direction</code>, which budgets read. Both flags need a baseline.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sparkforensics-analyze</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> candidate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --baseline</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> baseline</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --ignore-conf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;^spark\\.myjob\\.output\\.&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --noise-band-pct</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 5</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --format</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> json</span></span></code></pre></div><h2 id="several-budgets-and-several-candidates" tabindex="-1">Several budgets and several candidates <a class="header-anchor" href="#several-budgets-and-several-candidates" aria-label="Permalink to &quot;Several budgets and several candidates&quot;">​</a></h2><h3 id="several-regression-budgets" tabindex="-1">Several regression budgets <a class="header-anchor" href="#several-regression-budgets" aria-label="Permalink to &quot;Several regression budgets&quot;">​</a></h3><p><code>--max-regression-pct</code> checks one metric. To gate on several in one call, repeat <code>--regression-budget &lt;metric&gt;:&lt;pct&gt;</code>, or list them in a file passed with <code>--budgets &lt;file&gt;</code>. Both need <code>--baseline</code>, and each budget takes a <a href="./regression-metric-keys.html#regression-metric-keys">metric key</a> and a percentage of zero or more:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sparkforensics-analyze</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> candidate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --baseline</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> baseline</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --regression-budget</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> wallClock:10</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --regression-budget</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> gcTime:25</span></span></code></pre></div><p>The <code>--budgets</code> file is JSON with one key, <code>regression</code>, mapping a metric key to its percentage:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{ </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;regression&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;wallClock&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">10</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;gcTime&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">25</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;failedTaskRate&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } }</span></span></code></pre></div><p>The CLI refuses to run, with exit code 2 and a message naming the problem, for an unknown top-level key, an unknown metric key, a percentage that is not a non-negative number (in the file a JSON number, not a string; on the flag plain digits such as <code>10</code> or <code>2.5</code>), or a file that can&#39;t be read or isn&#39;t valid JSON.</p><p>The budgets combine like this:</p><ul><li><code>--max-regression-pct</code> with <code>--regression-metric</code> (default <code>wallClock</code>) still works and counts as one more budget next to the new ones.</li><li>Each metric can be budgeted once across the legacy pair, the repeated flag and the file. A metric named twice is a usage error (exit 2), even when both give the same percentage.</li><li>Each budget is checked on its own and gives one <code>max-regression</code> result that carries <code>metric</code>, the key it checks. Any violated budget makes the run exit <code>1</code>; otherwise an inconclusive one makes it exit <code>3</code>. A budget on a metric the baseline or the candidate log can&#39;t provide is inconclusive, never a pass.</li></ul><h3 id="per-stage-regression-budgets" tabindex="-1">Per-stage regression budgets <a class="header-anchor" href="#per-stage-regression-budgets" aria-label="Permalink to &quot;Per-stage regression budgets&quot;">​</a></h3><p><code>--max-regression-pct</code> and <code>--regression-budget</code> judge a whole-run metric. To gate on the stages themselves, repeat <code>--stage-regression-budget &lt;metric&gt;:&lt;pct&gt;</code> (with <code>--baseline</code>). The budget fails when any paired stage&#39;s metric grew by more than the percentage against its baseline stage. The metric is one of <code>executorRunTime</code>, <code>executorCpuTime</code>, <code>memoryBytesSpilled</code>, <code>diskBytesSpilled</code>, <code>shuffleReadBytes</code> and <code>shuffleWriteBytes</code>:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sparkforensics-analyze</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> candidate.zstd</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --baseline</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> baseline.zstd</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --stage-regression-budget</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> executorRunTime:25</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --stage-regression-budget</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> diskBytesSpilled:0</span></span></code></pre></div><ul><li>The stages come from the comparison&#39;s <code>stagePairs</code>. By default only <code>exact</code> and <code>structural</code> pairs count, since an <code>aligned</code> pair may compare different work. <code>--stage-quality exact,structural,aligned</code> chooses the qualities; each pair&#39;s <code>quality</code> and <code>score</code> are in the comparison output. Stages a re-plan left over are not paired and are not checked.</li><li>Each metric gives one <code>max-stage-regression</code> result carrying <code>metric</code>, whose detail names the worst offenders by <code>pairId</code>. A violation exits <code>1</code>.</li><li>A stage that grew from a zero baseline exceeds any percentage.</li><li>It is inconclusive (exit <code>3</code>) when no eligible stage pairs or the metric is missing on every one, never a pass. A comparison with <code>low</code> or <code>insufficient</code> confidence is still judged on the pairs it has.</li><li>A metric can be budgeted once. <code>--stage-quality</code> without <code>--stage-regression-budget</code>, an unknown metric or quality, and a metric named twice are usage errors (exit <code>2</code>), and so are <code>inputBytes</code> and <code>outputBytes</code>: workload volume has no regression direction.</li></ul><h3 id="baseline-from-a-history-server" tabindex="-1">Baseline from a History Server <a class="header-anchor" href="#baseline-from-a-history-server" aria-label="Permalink to &quot;Baseline from a History Server&quot;">​</a></h3><p><code>--baseline-shs-base-url &lt;url&gt; --baseline-app-id &lt;id&gt; [--baseline-attempt-id &lt;id&gt;]</code> fetch the baseline from a Spark History Server instead of reading a local path. The three flags mirror <code>--shs-base-url</code>, <code>--app-id</code> and <code>--attempt-id</code>, and the baseline can be on a different server than the candidate. Any candidate source works with it: a local log, or a History Server run.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sparkforensics-analyze</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --shs-base-url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://history-a:18080</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --app-id</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> application_1234_0002</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --baseline-shs-base-url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://history-b:18080</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --baseline-app-id</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> application_1234_0001</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --max-regression-pct</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 10</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --fail-on-introduced</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> critical</span></span></code></pre></div><ul><li><code>--baseline-shs-base-url</code> and <code>--baseline &lt;path&gt;</code> are mutually exclusive.</li><li><code>--baseline-app-id</code> is required with <code>--baseline-shs-base-url</code>, and <code>--baseline-attempt-id</code> needs <code>--baseline-shs-base-url</code>. Each is a usage error (exit <code>2</code>) before any fetch, as is a malformed value.</li><li>Every flag that needs a baseline (the budget flags, <code>--budgets</code>, <code>--stage-regression-budget</code>, <code>--stage-quality</code>, <code>--fail-on-introduced</code>, <code>--normalize-path</code>) accepts either kind of baseline.</li><li>A baseline fetch that fails exits <code>5</code>. With <code>--redact</code> the message names <code>The baseline</code> and carries no server address or application id, and no baseline identity reaches any output.</li></ul><h3 id="several-candidates" tabindex="-1">Several candidates <a class="header-anchor" href="#several-candidates" aria-label="Permalink to &quot;Several candidates&quot;">​</a></h3><p>Pass two or more logs as positional arguments, with a baseline (<code>--baseline</code> or <code>--baseline-shs-base-url</code>), to compare each against the same baseline. The baseline is parsed once. Two or more <code>--app-id</code> values with one <code>--shs-base-url</code> do the same for candidates fetched from one History Server: write <code>--app-id &lt;id&gt;:&lt;attempt&gt;</code> to name an attempt for one application. <code>--attempt-id</code> applies to a single <code>--app-id</code> only. Positional logs and <code>--shs-base-url</code> can&#39;t be mixed in one call. Output is NDJSON: one line per candidate, in argument order, written as each one finishes. <code>--out &lt;path&gt;</code> writes the lines to a file instead of stdout, and <code>--format ndjson</code> selects this output for a single candidate too. The mode can&#39;t be combined with <code>--export-html</code>, <code>--format json</code> or <code>--format md</code> (exit 2), and <code>--format ndjson</code> with a single <code>--app-id</code> is refused. <code>--redact</code>, <code>--thresholds</code>, <code>--impact</code>, <code>--type</code>, <code>--stage</code>, <code>--conf-keys</code>, <code>--conf-redact-regex</code> and every budget flag apply to each candidate.</p><p>Each line is one JSON object:</p><table tabindex="0"><thead><tr><th>Field</th><th>Meaning</th></tr></thead><tbody><tr><td><code>log</code></td><td>The candidate path, or the <code>--app-id</code> value, as given on the command line. With <code>--redact</code>, <code>candidate-&lt;n&gt;</code> instead, <code>n</code> being the candidate&#39;s 1-based position.</td></tr><tr><td><code>status</code></td><td><code>pass</code>, <code>violation</code>, <code>inconclusive</code> or <code>error</code>.</td></tr><tr><td><code>exitCode</code></td><td>The exit code this line alone would give: <code>0</code> for <code>pass</code>, <code>1</code> for <code>violation</code>, <code>3</code> for <code>inconclusive</code>, and for <code>error</code> <code>4</code> (the log can&#39;t be read or parsed) or <code>6</code> (an internal failure while analyzing it).</td></tr><tr><td><code>error</code></td><td>The message when <code>status</code> is <code>error</code>; otherwise <code>null</code>. With <code>--redact</code>, a generic message that names no path.</td></tr><tr><td><code>budgets</code></td><td>This candidate&#39;s budget results, each with <code>name</code>, <code>status</code> (<code>pass</code>, <code>violation</code> or <code>inconclusive</code>) and <code>detail</code>, plus <code>metric</code> on <code>max-regression</code> and <code>max-stage-regression</code>. Empty for an <code>error</code> line.</td></tr><tr><td><code>candidate</code></td><td>The candidate&#39;s report with its <code>metrics</code> and <code>effectiveConf</code> blocks, the same object the single-candidate JSON output carries under <code>candidate</code>. <code>null</code> for an <code>error</code> line.</td></tr><tr><td><code>comparison</code></td><td><code>verdict</code>, <code>confidence</code>, <code>reason</code>, <code>matchedCoverage</code>, <code>runtimeCoverage</code>, <code>metrics</code>, <code>findings</code>, <code>comparisonSchemaVersion</code>, <code>stagePairs</code>, <code>unmatched</code>, <code>replanned</code>, <code>bookkeepingStageIds</code> and <code>executionAlignment</code>, the same object the single-candidate JSON output carries under <code>comparison</code>. <code>null</code> for an <code>error</code> line.</td></tr></tbody></table><p>A line&#39;s <code>status</code> follows the single-candidate rules: <code>violation</code> if any budget result is a violation, else <code>inconclusive</code> if any is inconclusive (including the <code>run-complete</code> check for a log with no <code>ApplicationEnd</code>), else <code>pass</code>.</p><p>A candidate that can&#39;t be read or parsed doesn&#39;t stop the others. Its line has <code>status: &quot;error&quot;</code>, <code>exitCode: 4</code>, the message in <code>error</code>, and <code>null</code> for <code>candidate</code> and <code>comparison</code>, as a single-candidate run exits <code>4</code> for a candidate it can&#39;t parse. The process exit code is the worst line, in the order <code>6</code>, <code>5</code>, <code>4</code>, <code>1</code>, <code>3</code>, <code>0</code>, so an unreadable candidate outranks a violation and a violation outranks an inconclusive result.</p><p>Two failures stop the batch before any line is written:</p><ul><li>A usage error (bad flags or arguments, an invalid <code>--thresholds</code> or <code>--budgets</code> file) exits <code>2</code>.</li><li>A baseline that can&#39;t be read or parsed exits <code>5</code>. Fix the baseline and run the batch again.</li></ul><p>An internal failure that isn&#39;t tied to one candidate, such as an unwritable <code>--out</code> path, exits <code>6</code>.</p><p>With <code>--redact</code>, no candidate path or application id is written anywhere, since event-log file names usually carry the app id. <code>log</code> and the <code>stderr</code> line prefixes name each candidate by its 1-based position (<code>candidate-1</code>, <code>candidate-2</code>, ...), and an <code>error</code> line carries a generic message instead of the parser&#39;s, which may quote the path: <code>Candidate 2 could not be read or parsed.</code>, or <code>could not be analyzed</code> for an internal failure. An unreadable baseline prints <code>The baseline could not be read or parsed.</code> to <code>stderr</code>. A single-candidate run does the same, naming <code>The baseline</code> or <code>The candidate</code>.</p>`,108)])])}const g=o(i,[["render",d]]);export{u as __pageData,g as default};

package/public/docs/assets/user-guide_getting-started_ci-and-automation.md.C0pcQoNc.lean.js

@@ -0,0 +1 @@
+import{_ as o,o as t,c as a,a5 as s}from"./chunks/framework.DSg0KOwT.js";const u=JSON.parse('{"title":"CI and automation","description":"","frontmatter":{},"headers":[],"relativePath":"user-guide/getting-started/ci-and-automation.md","filePath":"user-guide/getting-started/ci-and-automation.md"}'),i={name:"user-guide/getting-started/ci-and-automation.md"};function d(n,e,c,r,l,h){return t(),a("div",null,[...e[0]||(e[0]=[s("",108)])])}const g=o(i,[["render",d]]);export{u as __pageData,g as default};

package/public/docs/assets/user-guide_getting-started_reading-the-dashboard.md.CGaxPX_1.js

@@ -0,0 +1 @@
+import{_ as t,o,c as a,a5 as n}from"./chunks/framework.DSg0KOwT.js";const u=JSON.parse('{"title":"Reading the dashboard","description":"","frontmatter":{},"headers":[],"relativePath":"user-guide/getting-started/reading-the-dashboard.md","filePath":"user-guide/getting-started/reading-the-dashboard.md"}'),s={name:"user-guide/getting-started/reading-the-dashboard.md"};function r(i,e,d,h,c,l){return o(),a("div",null,[...e[0]||(e[0]=[n('<h1 id="reading-the-dashboard" tabindex="-1">Reading the dashboard <a class="header-anchor" href="#reading-the-dashboard" aria-label="Permalink to &quot;Reading the dashboard&quot;">​</a></h1><p>How to read the dashboard once a run is loaded, including the advanced view and the rest of the top bar.</p><p>When parsing finishes, the dashboard shows a board of widgets, each in its own card with a title. Every widget that flags a problem uses the same convention: a colored impact dot (critical / warning / info) and an ALL-CAPS tag for the bottleneck category (<code>SKEW</code>, <code>SPILL</code>, <code>GC</code>, and so on: see <a href="./../understanding-findings.html">Understanding findings</a>). Widgets list every affected stage, not just the worst one. For a finding with a run-time estimate, the dot&#39;s color tracks how much run time it could save rather than how unusual the metric looks, so a small-looking anomaly with a big payoff can outrank a dramatic one that would barely move your run time. A finding with only a resource estimate, or none, keeps the level its check assigned. A critical finding is drawn in red whatever share of the run its saving is.</p><p>The board opens with a verdict: one line saying where to start, a short summary of what was found, and up to three numbered next steps. Each step says what the finding measured and what to try, and has a <strong>Show evidence</strong> button that opens the finding&#39;s detail widget in place, under the step. Findings on the same stage are folded into one step, because they usually share a cause and their savings overlap rather than add up. Each savings figure says what it counts: a time such as &quot;58.6s of run time&quot; is how much sooner the run could finish, while a resource figure such as &quot;3.0 GB-h of unused executor memory&quot; or &quot;0.2 core-h of task time (modeled)&quot; is cluster time a fix would free up, which cuts cost but may not shorten the run. A resource figure is always core time, never a duration, and says &quot;(modeled)&quot; when it rests on an assumed rate. A figure &quot;of idle core capacity&quot; counts allocated cores that ran no task, not work a fix removes. The steps rank &quot;By wall clock&quot;; a second list, &quot;By core time&quot;, ranks findings by the busy core time a fix removes, including findings with no run-time claim. A line under the summary states how much of the allocation ran no task. <strong>Copy next steps</strong> copies the whole plan as a plain checklist (run, verdict, and numbered steps with their stage and savings) to paste into a ticket or a message. Steps follow the same savings ranking as the rest of the board. When much of the run&#39;s executor capacity sat idle, the summary says so, without moving cluster size ahead of a bigger fix. When the Findings tab lists more findings, a <strong>More findings (n)</strong> link under the steps takes you there.</p><p>The verdict also says how the run ended. When every job succeeded it says so. When a job failed, the title says the run failed (or how many of its jobs did), quotes the first line of the reason Spark recorded, and puts the failure first in the next steps, ahead of any speed-up, since a job has to finish before its speed matters.</p><p>A run is called clean only when the log had everything its checks need. When something was missing, the run is never called clean: the Findings tab&#39;s <strong>Clean checks</strong> list says which checks could not run and, where Spark has one, the setting to turn on for the next run (for example <code>spark.eventLog.logBlockUpdates.enabled=true</code> for cache storage). If nothing else was found, the verdict title says so too.</p><p>A run scorecard sits under the verdict: <strong>Wall-clock</strong> (total run time), <strong>Efficiency</strong> (the share of that time with a stage running; higher is better; <strong>Not measured</strong> when no stage in the log recorded an end) and <strong>Unused core time</strong> (the share of executor core time that ran no task, the same idle figure a verdict step reports; lower is better). When the log has no complete application timing, one <strong>Timing unavailable</strong> notice replaces the three tiles. A collapsed <strong>New to Spark tuning?</strong> primer in the verdict explains stages, tasks, executors, shuffle and how to read savings. Stage labels such as <strong>Stage 7</strong> open that stage&#39;s details: how long it ran and what share of the run that was, then each of its findings with what it measured, what to try and a <strong>Show evidence</strong> button, followed by its overview, task, locality, I/O, spill, GC and plan sections (spill and GC only when the stage had them). Below it, two tabs split the rest of the board:</p><ol><li><strong>Findings</strong>: the flagged findings the verdict&#39;s steps do not already lead with, under <strong>More findings (n)</strong> and grouped by impact band (Critical, Warning, Info), or a line saying there are no more. Within a band, a recommendation row for a bottleneck type collapses into a summary row when it fires more than once; clicking the summary row expands its full list. Each row has one <strong>Show evidence</strong> button that opens its detail widget (the chart and per-stage numbers behind it) in place, or takes you to that widget when another row or the verdict already shows it. Widgets that found nothing fold away into a &quot;Clean checks&quot; disclosure. A check the log lacked the data for is listed there under <strong>Not checked on this log</strong>, not as a pass, with the reason and the setting to turn on: for example every per-stage check when no stage finished, or core usage, memory and executor churn when the log has no end-of-run record. This is the tab you land on.</li><li><strong>Full app report</strong>: the wall-clock and executor timelines, the stage table, and the reference-only cards, led by core usage by locality, which shows even on a clean run.</li></ol><p>Click a finding&#39;s tag to open its reference material in a slide-in panel beside the dashboard: the dashboard stays visible and interactive, so you can check a metric against the reference without losing your place. Esc closes the panel, even while you are reading or scrolling inside it. The topbar&#39;s <strong>Docs</strong> button opens these docs in a new tab.</p><h2 id="advanced-view" tabindex="-1">Advanced view <a class="header-anchor" href="#advanced-view" aria-label="Permalink to &quot;Advanced view&quot;">​</a></h2><p>The topbar has an <strong>Advanced view</strong> toggle. It&#39;s off by default, which keeps each widget to the finding itself and what to do about it. Turn it on to also show confidence levels, supporting evidence, and a page icon beside each finding&#39;s tag that opens its entry in these docs, plus a few extra table columns and the finding filter bar (impact, type, stage). A filter that is already active, for example from a shared link, keeps the filter bar visible either way. In the verdict, each step also says how its savings figure was estimated (measured or modeled, and whether the stage ran alone or shared the cluster, which makes the figure a range from a floor to an optimistic high), shows any confidence marker, and a line states how the steps are ordered. The scorecard switches from plain captions to the raw run and idle-time breakdown, and the newcomer primer is hidden. Advanced view also turns on single-key triage shortcuts: <code>j</code> and <code>k</code> step through the verdict&#39;s steps and then every finding row, <code>Enter</code> shows the focused finding&#39;s evidence, or expands a grouped finding, <code>f</code> jumps to the filters, and <code>1</code> and <code>2</code> switch between <strong>Findings</strong> and <strong>Full app report</strong>. They stay off in the default view, so they never surprise a first-time visitor or a screen-reader user. Your choice is remembered across runs.</p><h2 id="the-rest-of-the-topbar" tabindex="-1">The rest of the topbar <a class="header-anchor" href="#the-rest-of-the-topbar" aria-label="Permalink to &quot;The rest of the topbar&quot;">​</a></h2><p>Once a run is loaded, the topbar also carries a few more controls. The run name opens a menu of recent files, to switch to another run or load a new file. When the parser skipped malformed lines, a warning beside the name says how many. The count chip (&quot;4 critical&quot;) counts the same findings the verdict ranks. For critical findings with a run-time estimate, it adds the largest one&#39;s share of the run (&quot;1 critical, 2% of run&quot;), drawn in the band&#39;s color. Click it to jump to that band of the Findings list (a board filter hiding the band is cleared, with a notice saying so), or to the verdict when its steps hold every finding in the band. It reads <strong>Run failed</strong> when a job failed and there is no finding to count, <strong>No findings</strong> only when the verdict calls the run clean, and <strong>Not fully checked</strong> otherwise. For keyboard users, the first Tab stop is <strong>Skip to the verdict</strong>. <strong>New analysis</strong> goes back to the landing page to load another run; dropping a file onto the dashboard loads it too. <strong>Compare with another run</strong> keeps this run as the baseline and asks only for the other one (see <a href="./../run-comparison.html">Run comparison mode</a>). <strong>Plan graph</strong> opens an interactive node-and-edge view of the run&#39;s SQL execution plan, filterable down to I/O operators (scan, exchange), a broader &quot;basic&quot; set, or every operator. <strong>Export evidence</strong> downloads the current run&#39;s findings as a portable Markdown or JSON report, the same report the CLI produces, or as <strong>Download HTML dashboard</strong>: one <code>.html</code> file holding this dashboard for the run, which opens in any browser with no server, like the CLI&#39;s <code>--export-html</code> folder. Exported dashboards carry no docs links: finding tags and &quot;learn more&quot; references show as plain text, so look them up in these docs yourself. An exported dashboard shows the conclusions worked out when it was exported, and its footer names the tool, core version and build that produced it; it has no <strong>Export evidence</strong> menu of its own. A file written by an incompatible release opens to a message saying so; export the run again with your current release. Turn on <strong>Redact identifiers</strong> first if the export is headed outside the environment that produced it, since that pseudonymizes the app id, the app name and any host/IP tokens in all three formats. <strong>Keyboard shortcuts</strong> (press <code>?</code> from anywhere) lists every shortcut. Rounding it out: a <strong>Docs</strong> link and a theme toggle.</p>',13)])])}const p=t(s,[["render",r]]);export{u as __pageData,p as default};

package/public/docs/assets/{user-guide_getting-started_tuning-thresholds.md.B_MyjyZm.js → user-guide_getting-started_tuning-thresholds.md.BGVE-wrc.js}

@@ -1,4 +1,4 @@
-import{_ as s,o as t,c as a,a5 as o}from"./chunks/framework.DSg0KOwT.js";const p=JSON.parse('{"title":"Tuning detector thresholds","description":"","frontmatter":{},"headers":[],"relativePath":"user-guide/getting-started/tuning-thresholds.md","filePath":"user-guide/getting-started/tuning-thresholds.md"}'),i={name:"user-guide/getting-started/tuning-thresholds.md"};function d(n,e,r,h,l,c){return t(),a("div",null,[...e[0]||(e[0]=[o(`<h1 id="tuning-detector-thresholds" tabindex="-1">Tuning detector thresholds <a class="header-anchor" href="#tuning-detector-thresholds" aria-label="Permalink to &quot;Tuning detector thresholds&quot;">​</a></h1><p>How to run a detector check with your own threshold instead of its default.</p><p>Every check fires at a fixed default threshold. When your normal workload trips one on purpose, such as a join you skew deliberately, pass <code>--thresholds &lt;file&gt;</code> to run that check with your own value. The file is JSON, keyed by detector, then by threshold name:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
+import{_ as s,o as t,c as a,a5 as o}from"./chunks/framework.DSg0KOwT.js";const p=JSON.parse('{"title":"Tuning detector thresholds","description":"","frontmatter":{},"headers":[],"relativePath":"user-guide/getting-started/tuning-thresholds.md","filePath":"user-guide/getting-started/tuning-thresholds.md"}'),d={name:"user-guide/getting-started/tuning-thresholds.md"};function i(n,e,r,h,l,c){return t(),a("div",null,[...e[0]||(e[0]=[o(`<h1 id="tuning-detector-thresholds" tabindex="-1">Tuning detector thresholds <a class="header-anchor" href="#tuning-detector-thresholds" aria-label="Permalink to &quot;Tuning detector thresholds&quot;">​</a></h1><p>How to run a detector check with your own threshold instead of its default.</p><p>Every check fires at a fixed default threshold. When your normal workload trips one on purpose, such as a join you skew deliberately, pass <code>--thresholds &lt;file&gt;</code> to run that check with your own value. The file is JSON, keyed by detector, then by threshold name:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;skew&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;ratioWarn&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">6</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;shuffle&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;minBytes&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1073741824</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>The names, units and defaults are the <code>detectors</code> catalog in the CLI&#39;s JSON report (<code>thresholds</code> on each row): bytes are raw byte counts, times are milliseconds, and <code>*Pct</code>/<code>*Rate</code> values are fractions (<code>0.05</code> is 5%). A tier list such as <code>slowHost.ratioTiers</code> takes the same number of values, in ascending order. The <code>configAudit</code> checks can&#39;t be tuned: they compare your Spark settings against Spark&#39;s own defaults.</p><p>The CLI refuses to run, with exit code 2 and a message naming the problem, when the file can&#39;t be read, isn&#39;t valid JSON, or names an unknown detector or threshold, or a value of the wrong shape. It never falls back to the defaults silently.</p><p>A tuned run says so wherever it reports:</p><ul><li>Each finding from a tuned detector carries <code>tunedThresholds</code> (each overridden threshold&#39;s <code>value</code> and <code>default</code>), and its <code>validationRequired</code> text names them and, when the finding has an impact estimate, says that estimate is unvalidated. The estimates are calibrated against the default thresholds, so they were never checked for a finding your override lets through. Tuning <code>slowHost</code> also labels <code>stageSlowness</code> findings (as <code>slowHost.&lt;name&gt;</code>), because a slow host hides a stage&#39;s slowness finding, so the override decides which of those you see.</li><li>A clean check measured against a tuned threshold carries <code>tunedThresholds</code> too, with the tuned value and the default. Its <code>thresholdSummary</code> shows the tuned numbers for most detectors (for example <code>skew</code>, <code>gc</code>, <code>spill</code>, <code>slowHost</code>). A few summaries are fixed text with no number to tune.</li><li><code>summary.tunedThresholds</code> lists every tuned detector, and each tuned row of the <code>detectors</code> catalog shows the thresholds the run used.</li><li>The Markdown report adds a <code>Tuned thresholds</code> line to its header and a <code>tuned thresholds</code> line to each affected finding.</li></ul><p>An override equal to the default changes nothing and is not labeled. <code>--baseline</code> runs the baseline with the same overrides, so the comparison compares like with like. The budget flags are separate gates computed from the run&#39;s own figures; the one that recomputes a detector&#39;s figure, <code>--max-skew</code>, uses the file&#39;s <code>skew.minTasksForP95</code>, so it measures the same ratio the skew finding reports. <code>--export-html</code> writes the dashboard with the default thresholds, because the dashboard never tunes, and prints a note to stderr saying so. The browser dashboard has no tuning.</p>`,9)])])}const g=s(i,[["render",d]]);export{p as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>The names, units and defaults are the <code>detectors</code> catalog in the CLI&#39;s JSON report (<code>thresholds</code> on each row): bytes are raw byte counts, times are milliseconds, and <code>*Pct</code>/<code>*Rate</code> values are fractions (<code>0.05</code> is 5%). A tier list such as <code>slowHost.ratioTiers</code> takes the same number of values, in ascending order. The <code>configAudit</code> checks can&#39;t be tuned: they compare your Spark settings against Spark&#39;s own defaults.</p><p>The CLI refuses to run, with exit code 2 and a message naming the problem, when the file can&#39;t be read, isn&#39;t valid JSON, or names an unknown detector or threshold, or a value of the wrong shape. It never falls back to the defaults silently.</p><p>A tuned run says so wherever it reports:</p><ul><li>Each finding from a tuned detector carries <code>tunedThresholds</code> (each overridden threshold&#39;s <code>value</code> and <code>default</code>), and its <code>validationRequired</code> text names them and, when the finding has an impact estimate, says that estimate is unvalidated. The estimates are calibrated against the default thresholds, so they were never checked for a finding your override lets through. Tuning <code>slowHost</code> also labels <code>stageSlowness</code> findings (as <code>slowHost.&lt;name&gt;</code>), because a slow host hides a stage&#39;s slowness finding, so the override decides which of those you see. Tuning <code>skew</code> labels <code>straggler</code> findings the same way (as <code>skew.&lt;name&gt;</code>), because <code>straggler</code> reports the slow tails <code>skew</code>&#39;s thresholds leave to it.</li><li>A clean check measured against a tuned threshold carries <code>tunedThresholds</code> too, with the tuned value and the default. Its <code>thresholdSummary</code> shows the tuned numbers for most detectors (for example <code>skew</code>, <code>gc</code>, <code>spill</code>, <code>slowHost</code>). A few summaries are fixed text with no number to tune.</li><li><code>summary.tunedThresholds</code> lists every tuned detector, and each tuned row of the <code>detectors</code> catalog shows the thresholds the run used.</li><li>The Markdown report adds a <code>Tuned thresholds</code> line to its header and a <code>tuned thresholds</code> line to each affected finding.</li></ul><p>An override equal to the default changes nothing and is not labeled. <code>--baseline</code> runs the baseline with the same overrides, so the comparison compares like with like. The budget flags are separate gates computed from the run&#39;s own figures; the one that recomputes a detector&#39;s figure, <code>--max-skew</code>, uses the file&#39;s <code>skew.minTasksForP95</code>, so it measures the same ratio the skew finding reports. <code>--export-html</code> writes the dashboard with the default thresholds, because the dashboard never tunes, and prints a note to stderr saying so. The browser dashboard has no tuning.</p>`,9)])])}const g=s(d,[["render",i]]);export{p as __pageData,g as default};

package/public/docs/assets/{user-guide_getting-started_tuning-thresholds.md.B_MyjyZm.lean.js → user-guide_getting-started_tuning-thresholds.md.BGVE-wrc.lean.js}

@@ -1 +1 @@
-import{_ as s,o as t,c as a,a5 as o}from"./chunks/framework.DSg0KOwT.js";const p=JSON.parse('{"title":"Tuning detector thresholds","description":"","frontmatter":{},"headers":[],"relativePath":"user-guide/getting-started/tuning-thresholds.md","filePath":"user-guide/getting-started/tuning-thresholds.md"}'),i={name:"user-guide/getting-started/tuning-thresholds.md"};function d(n,e,r,h,l,c){return t(),a("div",null,[...e[0]||(e[0]=[o("",9)])])}const g=s(i,[["render",d]]);export{p as __pageData,g as default};
+import{_ as s,o as t,c as a,a5 as o}from"./chunks/framework.DSg0KOwT.js";const p=JSON.parse('{"title":"Tuning detector thresholds","description":"","frontmatter":{},"headers":[],"relativePath":"user-guide/getting-started/tuning-thresholds.md","filePath":"user-guide/getting-started/tuning-thresholds.md"}'),d={name:"user-guide/getting-started/tuning-thresholds.md"};function i(n,e,r,h,l,c){return t(),a("div",null,[...e[0]||(e[0]=[o("",9)])])}const g=s(d,[["render",i]]);export{p as __pageData,g as default};

package/public/docs/assets/{user-guide_mcp-tools.md.C65SjWUL.js → user-guide_mcp-tools.md.49r3L2YE.js}

@@ -1,4 +1,4 @@
-import{_ as s,o as t,c as a,a5 as i}from"./chunks/framework.DSg0KOwT.js";const u=JSON.parse('{"title":"MCP tools reference","description":"","frontmatter":{},"headers":[],"relativePath":"user-guide/mcp-tools.md","filePath":"user-guide/mcp-tools.md"}'),o={name:"user-guide/mcp-tools.md"};function n(d,e,r,l,c,h){return t(),a("div",null,[...e[0]||(e[0]=[i(`<h1 id="mcp-tools-reference" tabindex="-1">MCP tools reference <a class="header-anchor" href="#mcp-tools-reference" aria-label="Permalink to &quot;MCP tools reference&quot;">​</a></h1><p>SparkForensics has an MCP server with eight tools, so an MCP-aware client (or an AI agent) can diagnose a run without opening the dashboard.</p><p>Five of the eight tools (<code>list_runs</code>, <code>diagnose_run</code>, <code>get_run_summary</code>, <code>compare_runs</code>, <code>get_finding_evidence</code>) accept an optional <code>redact: boolean</code> parameter (default <code>false</code>) that pseudonymizes the app id and any host/IP tokens in the response (<code>app-1</code>, <code>host-1</code>, ...), so a result can be shared outside the environment that produced it. The app name is as identifying as the id, so every tool replaces it with the app id&#39;s pseudonym. It also pseudonymizes the value of any field named <code>host</code>, and drops the message and stack text of failed-task errors and the failure reason of a failed stage or job, which can carry file paths and data values that no pattern recognizes. On <code>compare_runs</code>, <code>runIdA</code>/<code>runIdB</code> are caller-supplied identifiers, not Spark application ids, so there&#39;s no single app-id field to redact; <code>redact</code> instead scans stage names and other free text for embedded app ids and host/IP tokens and pseudonymizes those. <code>list_runs</code> pseudonymizes every run&#39;s app id and name consistently, so two attempts of the same app still redact to the same identity across the list.</p><h2 id="connecting-a-client" tabindex="-1">Connecting a client <a class="header-anchor" href="#connecting-a-client" aria-label="Permalink to &quot;Connecting a client&quot;">​</a></h2><p>Run the server with <code>npx</code>:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>npx sparkforensics-mcp</span></span></code></pre></div><p>Or point an MCP client (Claude Desktop, Claude Code) at it with this config:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
+import{_ as s,o as t,c as a,a5 as i}from"./chunks/framework.DSg0KOwT.js";const u=JSON.parse('{"title":"MCP tools reference","description":"","frontmatter":{},"headers":[],"relativePath":"user-guide/mcp-tools.md","filePath":"user-guide/mcp-tools.md"}'),o={name:"user-guide/mcp-tools.md"};function n(d,e,r,l,c,h){return t(),a("div",null,[...e[0]||(e[0]=[i(`<h1 id="mcp-tools-reference" tabindex="-1">MCP tools reference <a class="header-anchor" href="#mcp-tools-reference" aria-label="Permalink to &quot;MCP tools reference&quot;">​</a></h1><p>SparkForensics has an MCP server with eight tools, so an MCP-aware client (or an AI agent) can diagnose a run without opening the dashboard.</p><p>Five of the eight tools (<code>list_runs</code>, <code>diagnose_run</code>, <code>get_run_summary</code>, <code>compare_runs</code>, <code>get_finding_evidence</code>) accept an optional <code>redact: boolean</code> parameter (default <code>false</code>) that pseudonymizes the app id and any host/IP tokens in the response (<code>app-1</code>, <code>host-1</code>, ...), so a result can be shared outside the environment that produced it. The app name is as identifying as the id, so every tool replaces it with the app id&#39;s pseudonym. It also pseudonymizes the value of any field named <code>host</code>, and drops the message and stack text of failed-task errors and the failure reason of a failed stage or job, which can carry file paths and data values that no pattern recognizes. On <code>compare_runs</code>, <code>runIdA</code>/<code>runIdB</code> are caller-supplied identifiers, not Spark application ids, so there&#39;s no single app-id field to redact beyond <code>baselineApp</code> and <code>candidateApp</code>; <code>redact</code> instead scans stage names and other free text for embedded app ids and host/IP tokens and pseudonymizes those. <code>list_runs</code> pseudonymizes every run&#39;s app id and name consistently, so two attempts of the same app still redact to the same identity across the list.</p><h2 id="connecting-a-client" tabindex="-1">Connecting a client <a class="header-anchor" href="#connecting-a-client" aria-label="Permalink to &quot;Connecting a client&quot;">​</a></h2><p>Run the server with <code>npx</code>:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>npx sparkforensics-mcp</span></span></code></pre></div><p>Or point an MCP client (Claude Desktop, Claude Code) at it with this config:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;mcpServers&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    &quot;sparkforensics&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;command&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;npx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>

package/public/docs/assets/{user-guide_mcp-tools_compare-runs.md.Cc_gLoix.js → user-guide_mcp-tools_compare-runs.md.BQ_kIptC.js}

@@ -1,4 +1,4 @@
-import{_ as i,o as a,c as e,a5 as t}from"./chunks/framework.DSg0KOwT.js";const c=JSON.parse('{"title":"compare_runs","description":"","frontmatter":{},"headers":[],"relativePath":"user-guide/mcp-tools/compare-runs.md","filePath":"user-guide/mcp-tools/compare-runs.md"}'),n={name:"user-guide/mcp-tools/compare-runs.md"};function h(o,s,l,d,p,k){return a(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="compare-runs" tabindex="-1"><code>compare_runs</code> <a class="header-anchor" href="#compare-runs" aria-label="Permalink to &quot;\`compare_runs\`&quot;">​</a></h1><p>Reference for the <code>compare_runs</code> tool of the SparkForensics MCP server.</p><p>Compare two runs: the comparison page&#39;s verdict, metric deltas (<code>metrics</code>) and categorized findings delta (<code>findings</code>), and the share of executor run time in paired stages (<code>runtimeCoverage</code>). The result carries the same <code>verdict</code>, <code>confidence</code>, <code>reason</code>, <code>matchedCoverage</code>, <code>runtimeCoverage</code>, <code>metrics</code>, <code>findings</code>, <code>comparisonSchemaVersion</code>, <code>unmatched</code>, <code>replanned</code>, <code>bookkeepingStageIds</code> and <code>executionAlignment</code> as the <code>comparison</code> object of the CLI&#39;s <code>--baseline</code> JSON output, plus <code>stagePairs</code> when <code>include</code> asks for it (the CLI always carries it), plus <code>runIdA</code> and <code>runIdB</code>. <code>metricDeltas</code> and <code>findingsDelta</code> repeat <code>metrics</code> and <code>findings</code> under their earlier names; they are deprecated and will be removed in a later release. <code>verdict</code> is the headline the dashboard&#39;s comparison page opens with (the baseline is <code>runIdA</code>/<code>sourceA</code>, the candidate <code>runIdB</code>/<code>sourceB</code>): a <code>title</code> such as &quot;The candidate finished 9.9s faster than the baseline (37%)&quot;, or a failed-job headline when either run had jobs fail, a <code>tone</code> (<code>better</code>, <code>worse</code>, <code>same</code> or <code>unknown</code>), and <code>sentences</code> naming which cost metrics and finding categories moved each way. When either log has no <code>ApplicationEnd</code> event, the title compares how much run time each log covers (&quot;The candidate&#39;s log covers 2.0s less run time than the baseline&#39;s&quot;) and the tone is <code>unknown</code>.</p><p>Parameters:</p><ul><li><code>runIdA</code> / <code>sourceA</code>: identify the baseline (same <code>source</code> shape as above)</li><li><code>runIdB</code> / <code>sourceB</code>: identify the candidate</li><li><code>redact</code>: <code>boolean</code> (default <code>false</code>), pseudonymizes any app id or host/IP tokens embedded in free text (stage names and similar) in the response: see the note at the top of this page</li><li><code>include</code>: <code>[&quot;stagePairs&quot;]</code> (optional), adds <code>stagePairs</code>, one row per paired stage. It is left out by default because it grows with the number of stages.</li><li><code>normalizePath</code>: <code>string[]</code> (optional), regular expressions whose every match in a plan node&#39;s text is replaced with a fixed token before stages are paired, so text that is specific to your runs does not keep the same stage from pairing. Despite the name it is a generic pattern, not only for paths. It affects stage pairing, <code>runtimeCoverage</code> and <code>confidence</code>, never the findings. At most 16 patterns of 200 characters each. An invalid pattern, or one that matches the empty string, fails the call before any log is read. A pattern that backtracks catastrophically can stall the server, and the length cap does not prevent that: an agent passing patterns should keep them simple and anchored.</li><li><code>format</code>: <code>&quot;json&quot; | &quot;md&quot;</code> (default <code>&quot;json&quot;</code>), switches <code>content[0].text</code> to a rendered Markdown report instead of JSON. <code>structuredContent</code> always stays JSON-shaped, regardless of <code>format</code>.</li></ul><p>Each side needs either a <code>runId</code> or a <code>source</code>, and you can mix them: a cached run ID for the baseline, a fresh file for the candidate.</p><p>Example call (add <code>&quot;include&quot;: [&quot;stagePairs&quot;]</code> to the arguments for the pair rows):</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
+import{_ as i,o as e,c as a,a5 as t}from"./chunks/framework.DSg0KOwT.js";const r=JSON.parse('{"title":"compare_runs","description":"","frontmatter":{},"headers":[],"relativePath":"user-guide/mcp-tools/compare-runs.md","filePath":"user-guide/mcp-tools/compare-runs.md"}'),n={name:"user-guide/mcp-tools/compare-runs.md"};function o(d,s,h,l,p,k){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="compare-runs" tabindex="-1"><code>compare_runs</code> <a class="header-anchor" href="#compare-runs" aria-label="Permalink to &quot;\`compare_runs\`&quot;">​</a></h1><p>Reference for the <code>compare_runs</code> tool of the SparkForensics MCP server.</p><p>Compare two runs: the comparison page&#39;s verdict, metric deltas (<code>metrics</code>) and categorized findings delta (<code>findings</code>), and the share of executor run time in paired stages (<code>runtimeCoverage</code>). The result carries the same <code>generator</code> (the <code>sparkforensics-mcp</code> build that wrote the result), <code>verdict</code>, <code>baselineApp</code> and <code>candidateApp</code> (each run&#39;s Spark application <code>id</code> and <code>attemptId</code>), <code>confidence</code>, <code>reason</code>, <code>matchedCoverage</code>, <code>runtimeCoverage</code>, <code>metrics</code>, <code>findings</code>, <code>comparisonSchemaVersion</code>, <code>unmatched</code>, <code>replanned</code>, <code>bookkeepingStageIds</code>, <code>executionAlignment</code> and <code>comparability</code> as the <code>comparison</code> object of the CLI&#39;s <code>--baseline</code> JSON output, plus <code>stagePairs</code> when <code>include</code> asks for it (the CLI always carries it), plus <code>runIdA</code> and <code>runIdB</code>, which are handles for the runs this server process has cached and differ per tool by design: match runs by <code>baselineApp</code> and <code>candidateApp</code>. Each row of <code>findings</code> lists its stage names in <code>stages</code> and the same names with the directories of their call-site paths removed in <code>stageLabels</code>; each <code>stagePairs</code> row has the same kind of label in <code>stageLabel</code>. The raw names in <code>stages</code> still carry those paths, and <code>redact</code> does not remove them, so show <code>stageLabels</code> and <code>stageLabel</code>. <code>metricDeltas</code> and <code>findingsDelta</code> repeat <code>metrics</code> and <code>findings</code> under their earlier names; they are deprecated and will be removed in a later release. <code>verdict</code> is the headline the dashboard&#39;s comparison page opens with (the baseline is <code>runIdA</code>/<code>sourceA</code>, the candidate <code>runIdB</code>/<code>sourceB</code>): a <code>title</code> such as &quot;The candidate finished 9.9s faster than the baseline (37%)&quot;, or a failed-job headline when either run had jobs fail, a <code>tone</code> (<code>better</code>, <code>worse</code>, <code>same</code>, <code>unknown</code>, <code>equivalent</code> or <code>mixed</code>), and <code>sentences</code> naming which cost metrics and finding categories moved each way. When either log has no <code>ApplicationEnd</code> event, the title compares how much run time each log covers (&quot;The candidate&#39;s log covers 2.0s less run time than the baseline&#39;s&quot;) and the tone is <code>unknown</code>.</p><p>Parameters:</p><ul><li><code>runIdA</code> / <code>sourceA</code>: identify the baseline (same <code>source</code> shape as above)</li><li><code>runIdB</code> / <code>sourceB</code>: identify the candidate</li><li><code>redact</code>: <code>boolean</code> (default <code>false</code>), pseudonymizes any app id or host/IP tokens embedded in free text (stage names and similar) in the response: see the note at the top of this page</li><li><code>include</code>: <code>[&quot;stagePairs&quot;]</code> (optional), adds <code>stagePairs</code>, one row per paired stage. It is left out by default because it grows with the number of stages.</li><li><code>normalizePath</code>: <code>string[]</code> (optional), regular expressions whose every match in a plan node&#39;s text is replaced with a fixed token before stages are paired, so text that is specific to your runs does not keep the same stage from pairing. Despite the name it is a generic pattern, not only for paths. It affects stage pairing, <code>runtimeCoverage</code> and <code>confidence</code>, never the findings. At most 16 patterns of 200 characters each. An invalid pattern, or one that matches the empty string, fails the call before any log is read. A pattern that backtracks catastrophically can stall the server, and the length cap does not prevent that: an agent passing patterns should keep them simple and anchored.</li><li><code>ignoreConf</code>: <code>string[]</code> (optional), regular expressions matched against Spark configuration keys. A key that matches one is left out of <code>comparability.conf</code>, for keys that differ by design such as a per-run output path. Same limits as <code>normalizePath</code>; an invalid pattern fails the call before any log is read.</li><li><code>noiseBand</code>: <code>number</code> from 0 to 1 (optional, default <code>0.02</code>), the share of the baseline value under which a metric row is <code>withinNoise</code>. It never changes a row&#39;s <code>direction</code>.</li><li><code>format</code>: <code>&quot;json&quot; | &quot;md&quot;</code> (default <code>&quot;json&quot;</code>), switches <code>content[0].text</code> to a rendered Markdown report instead of JSON. <code>structuredContent</code> always stays JSON-shaped, regardless of <code>format</code>.</li></ul><p><code>comparability</code> says whether the two runs can be read against each other:</p><ul><li><code>conf</code>: <code>equal</code> (<code>true</code> when <code>differences</code> is empty after the ignore list; <code>null</code> when a log records no Spark properties), <code>differences</code> (rows of <code>key</code>, <code>baseline</code> and <code>candidate</code>, a side that does not set the key is <code>null</code>), <code>ignoredKeys</code> (keys that differ but are left out: per-run identity keys and the <code>ignoreConf</code> matches) and <code>withheldKeys</code> (secrets, never compared or shown). Values come from the same builder as the run report&#39;s <code>effectiveConf</code>, so a key withheld there is withheld here, including the CLI&#39;s <code>--conf-redact-regex</code> matches.</li><li><code>plan</code>: <code>equal</code>, <code>unmatched</code> (stage counts per side) and <code>replanned</code> (groups).</li><li><code>volume</code>: <code>inputBytes</code>, <code>outputRows</code> and <code>outputBytes</code>, each with <code>baseline</code>, <code>candidate</code> and <code>relativeDifference</code>, and <code>equal</code>: output rows equal, input and output bytes within the noise band. <code>equal</code> is <code>null</code> unless output rows or output bytes are measured on both sides; input bytes alone never make it <code>true</code>.</li><li><code>capacity</code>: mean and peak executors per side.</li><li><code>overlapMs</code>: how long the two run windows overlap.</li><li><code>wallClockBridge</code>: <code>wallClock</code>, <code>taskTime</code>, <code>meanExecutors</code> and <code>taskShareOfAllocation</code>, each with <code>baseline</code>, <code>candidate</code> and <code>ratio</code>, and <code>explainedWallClock</code>, the task-time ratio over the product of the other two.</li><li><code>noiseBand</code>: the band in use.</li></ul><p>The <code>verdict</code> tone is <code>equivalent</code> when <code>conf.equal</code>, <code>plan.equal</code> and <code>volume.equal</code> are all <code>true</code> and either the wall-clock gap is within the noise band or a bridge factor (mean executors, task time or task share of allocation) moved past it and explains the gap. When configuration and plan agree but the gap is past noise and no factor explains it, the tone stays <code>better</code> or <code>worse</code> from the wall clock and the title ends &quot;no measured factor explains it&quot;. When <code>volume.equal</code> is <code>null</code>, the tone also comes from the wall clock and the title reads &quot;Same configuration and plan. Output was not compared.&quot; The tone is <code>mixed</code> when the wall clock and executor run-time or allocated core-hours move opposite ways past the noise band and the configuration or plan differs. A failed job or an incomplete log still leads the verdict.</p><p>Each side needs either a <code>runId</code> or a <code>source</code>, and you can mix them: a cached run ID for the baseline, a fresh file for the candidate.</p><p>Example call (add <code>&quot;include&quot;: [&quot;stagePairs&quot;]</code> to the arguments for the pair rows):</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;name&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;compare_runs&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;arguments&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    &quot;sourceA&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;path&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;baseline.zstd&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
@@ -7,6 +7,9 @@ import{_ as i,o as a,c as e,a5 as t}from"./chunks/framework.DSg0KOwT.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Example response with <code>include: [&quot;stagePairs&quot;]</code> (<code>metrics</code> and <code>metricDeltas</code> trimmed to their first row of 13, and each pair&#39;s <code>deltas</code> to three of its eight metrics):</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;runIdA&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;aaaa1111-...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;runIdB&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;bbbb2222-...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;generator&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;name&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;sparkforensics-mcp&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;version&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;0.9.0&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;buildId&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;9c1f3a7e2b4d&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;baselineApp&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;application_0000000000000_0001&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;attemptId&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;candidateApp&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;application_0000000000000_0002&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;attemptId&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;verdict&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;title&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;The candidate finished 1.0s faster than the baseline (50%)&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;tone&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;better&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;sentences&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [] },</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;confidence&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ok&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;reason&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
@@ -19,10 +22,11 @@ import{_ as i,o as a,c as e,a5 as t}from"./chunks/framework.DSg0KOwT.js";const c
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;baseline&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;candidate&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;delta&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">-1000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;direction&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;improvement&quot;</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;direction&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;improvement&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;withinNoise&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ],</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;findings&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;introduced&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [], </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;resolved&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [] },</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;findings&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;introduced&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [], </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;resolved&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [], </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;changed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [] },</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;comparisonSchemaVersion&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;stagePairs&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    {</span></span>
@@ -49,8 +53,9 @@ import{_ as i,o as a,c as e,a5 as t}from"./chunks/framework.DSg0KOwT.js";const c
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;baseline&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;candidate&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;delta&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">-1000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;direction&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;improvement&quot;</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;direction&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;improvement&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;withinNoise&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ],</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;findingsDelta&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;introduced&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [], </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;resolved&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [] }</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Each <code>findings.introduced</code>/<code>resolved</code> row is <code>{ rule, type, impactBand, baseCount, candCount, delta, stages }</code>, with <code>stages</code> naming the affected stages. A <code>metrics</code> row&#39;s <code>direction</code> is <code>improvement</code>, <code>regression</code>, <code>unchanged</code>, <code>neutral</code> (a volume metric, where more isn&#39;t worse) or <code>unavailable</code>, and an unavailable row carries an <code>unavailableReason</code>.</p><p>The comparison block (<code>comparisonSchemaVersion</code> <code>1</code>) holds:</p><ul><li><code>stagePairs</code> (only with <code>include</code>): one entry per pair of stages, <code>pairId</code> (stable for one pair of runs; key on it), <code>baseStageIds</code> and <code>candStageIds</code>, <code>quality</code> (<code>exact</code>, <code>structural</code> or <code>aligned</code>), <code>score</code> (0 to 1) and <code>deltas</code>. <code>deltas</code> has one <code>{ baseline, candidate, delta }</code> entry for each of <code>executorRunTime</code>, <code>executorCpuTime</code> (ms), <code>memoryBytesSpilled</code>, <code>diskBytesSpilled</code>, <code>inputBytes</code>, <code>outputBytes</code>, <code>shuffleReadBytes</code> and <code>shuffleWriteBytes</code>. The figures count every task attempt of the stage, failed ones included, the same sums the whole-run <code>metrics</code> use; a figure the log did not record is <code>null</code>. A stage&#39;s own record in the run report keeps the latest attempt&#39;s figures.</li><li><code>unmatched</code>: <code>{ baseStageIds, candStageIds }</code>, the stages that paired with nothing and sit in no replanned group.</li><li><code>replanned</code>: one group for each aligned pair of SQL executions whose stage counts differ and that left stages unpaired (a broadcast join that took out an exchange, for example). A group holds <code>baseExecutionId</code>, <code>candExecutionId</code>, <code>baseStageIds</code> and <code>candStageIds</code> (the leftover stages per side) and <code>deltas</code>, the total of each of the eight delta metrics over the leftover stages of each side, as <code>{ baseline, candidate, delta }</code> entries like a pair&#39;s. Leftover stages under an execution pair with equal stage counts are <code>unmatched</code>.</li><li><code>bookkeepingStageIds</code>: <code>{ baseStageIds, candStageIds }</code>, stages that only read the Delta log or its checkpoints. They are in no pair, not in <code>unmatched</code> and not in the coverage.</li><li><code>runtimeCoverage</code>: the share of both runs&#39; executor run time (bookkeeping stages excluded) in paired and replanned stages, or <code>null</code> when neither run recorded any.</li><li><code>executionAlignment</code>: how the SQL executions of the two runs lined up: <code>baseExecutions</code> and <code>candExecutions</code> (executions with at least one stage outside the Delta bookkeeping set), <code>pairedExecutions</code>, <code>agreement</code> (<code>pairedExecutions / min(baseExecutions, candExecutions)</code>, <code>null</code> when either run has none), <code>accepted</code> (false when <code>agreement</code> is under 0.5: the runs share too little SQL work to be one job, and no stage pairs) and <code>bounded</code> (true when the alignment ran in its band form, which happens above 1,000,000 execution pairs).</li><li><code>matchedCoverage</code>: the share of stages paired by the exact key alone, by count.</li></ul><p>A pair&#39;s <code>quality</code> is <code>exact</code> (same normalized name and plan text), <code>structural</code> (same plan shape and attribute names, different text) or <code>aligned</code> (different structure with similar text, or no plan to compare and paired by position among stages of one name). <code>score</code> is 1 for <code>exact</code>, the text similarity for the other two, and 0.5 for a pair made by position. See <a href="./../run-comparison/how-stages-are-matched.html">How stages are matched</a>.</p><p><code>confidence</code> is <code>ok</code>, <code>low</code> or <code>insufficient</code>, and <code>reason</code> says why when it is not <code>ok</code>. It is <code>low</code> when the two runs&#39; names differ, or when under 90% of executor run time is in paired stages (<code>runtimeCoverage</code>), for example &quot;Only 62% of executor run time is in matched stages&quot;. It is <code>insufficient</code> when neither run recorded any executor run time.</p>`,15)])])}const E=i(n,[["render",h]]);export{c as __pageData,E as default};
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;findingsDelta&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;introduced&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [], </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;resolved&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [], </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;changed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [] }</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>A finding is the same finding in both runs when it has the same type, rule and location (a paired stage, a paired SQL execution, an audited setting, or the whole run), whatever its value or impact band. Each <code>findings.introduced</code>/<code>resolved</code> row groups the findings of one rule and band that have no counterpart in the other run: <code>{ rule, type, impactBand, baseCount, candCount, delta, stages, keys }</code>, with <code>baseCount</code> 0 on an introduced row, <code>candCount</code> 0 on a resolved row, and <code>stages</code> naming the stages the findings sit on. <code>keys</code> lists the <code>key</code> of each finding the row counts, as <a href="./diagnose-run.html"><code>diagnose_run</code></a> reports it for the run the findings are in (the candidate for an introduced row, the baseline for a resolved one), so a row points at the findings it counts. Each <code>findings.changed</code> row groups the findings both runs have whose impact band differs: <code>{ rule, type, baseImpactBand, candImpactBand, count, stages, keys, baseKeys }</code>, with <code>stages</code> naming the candidate&#39;s stages, <code>keys</code> the candidate&#39;s finding keys and <code>baseKeys</code> the baseline&#39;s. The two differ when the aligner paired stages that do not share a fingerprint. A <code>metrics</code> row&#39;s <code>direction</code> is <code>improvement</code>, <code>regression</code>, <code>unchanged</code>, <code>neutral</code> (a volume metric, where more isn&#39;t worse) or <code>unavailable</code>, and an unavailable row carries an <code>unavailableReason</code>.</p><p>The comparison block (<code>comparisonSchemaVersion</code> <code>1</code>) holds:</p><ul><li><code>stagePairs</code> (only with <code>include</code>): one entry per pair of stages, <code>pairId</code> (stable for one pair of runs; key on it), <code>baseStageIds</code> and <code>candStageIds</code>, <code>stageLabel</code> (the pair&#39;s baseline stage name with call-site directories removed; the row has no raw name), <code>quality</code> (<code>exact</code>, <code>structural</code> or <code>aligned</code>), <code>score</code> (0 to 1) and <code>deltas</code>. <code>deltas</code> has one <code>{ baseline, candidate, delta }</code> entry for each of <code>executorRunTime</code>, <code>executorCpuTime</code> (ms), <code>memoryBytesSpilled</code>, <code>diskBytesSpilled</code>, <code>inputBytes</code>, <code>outputBytes</code>, <code>shuffleReadBytes</code> and <code>shuffleWriteBytes</code>. The figures count every task attempt of the stage, failed ones included, the same sums the whole-run <code>metrics</code> use; a figure the log did not record is <code>null</code>. A stage&#39;s own record in the run report keeps the latest attempt&#39;s figures.</li><li><code>unmatched</code>: <code>{ baseStageIds, candStageIds }</code>, the stages that paired with nothing and sit in no replanned group.</li><li><code>replanned</code>: one group for each aligned pair of SQL executions whose stage counts differ and that left stages unpaired (a broadcast join that took out an exchange, for example). A group holds <code>baseExecutionId</code>, <code>candExecutionId</code>, <code>baseStageIds</code> and <code>candStageIds</code> (the leftover stages per side) and <code>deltas</code>, the total of each of the eight delta metrics over the leftover stages of each side, as <code>{ baseline, candidate, delta }</code> entries like a pair&#39;s. Leftover stages under an execution pair with equal stage counts are <code>unmatched</code>.</li><li><code>bookkeepingStageIds</code>: <code>{ baseStageIds, candStageIds }</code>, stages that only read the Delta log or its checkpoints. They are in no pair, not in <code>unmatched</code> and not in the coverage.</li><li><code>runtimeCoverage</code>: the share of both runs&#39; executor run time (bookkeeping stages excluded) in paired and replanned stages, or <code>null</code> when neither run recorded any.</li><li><code>executionAlignment</code>: how the SQL executions of the two runs lined up: <code>baseExecutions</code> and <code>candExecutions</code> (executions with at least one stage outside the Delta bookkeeping set), <code>pairedExecutions</code>, <code>agreement</code> (<code>pairedExecutions / min(baseExecutions, candExecutions)</code>, <code>null</code> when either run has none), <code>accepted</code> (false when <code>agreement</code> is under 0.5: the runs share too little SQL work to be one job, and no stage pairs) and <code>bounded</code> (true when the alignment ran in its band form, which happens above 1,000,000 execution pairs).</li><li><code>matchedCoverage</code>: the share of stages paired by the exact key alone, by count.</li></ul><p>A pair&#39;s <code>quality</code> is <code>exact</code> (same normalized name and plan text), <code>structural</code> (same plan shape and attribute names, different text) or <code>aligned</code> (different structure with similar text, or no plan to compare and paired by position among stages of one name). <code>score</code> is 1 for <code>exact</code>, the text similarity for the other two, and 0.5 for a pair made by position. See <a href="./../run-comparison/how-stages-are-matched.html">How stages are matched</a>.</p><p><code>confidence</code> is <code>ok</code>, <code>low</code> or <code>insufficient</code>, and <code>reason</code> says why when it is not <code>ok</code>. It is <code>low</code> when the two runs&#39; names differ, or when under 90% of executor run time is in paired stages (<code>runtimeCoverage</code>), for example &quot;Only 62% of executor run time is in matched stages&quot;. It is <code>insufficient</code> when neither run recorded any executor run time.</p>`,18)])])}const E=i(n,[["render",o]]);export{r as __pageData,E as default};

package/public/docs/assets/user-guide_mcp-tools_compare-runs.md.BQ_kIptC.lean.js

@@ -0,0 +1 @@
+import{_ as i,o as e,c as a,a5 as t}from"./chunks/framework.DSg0KOwT.js";const r=JSON.parse('{"title":"compare_runs","description":"","frontmatter":{},"headers":[],"relativePath":"user-guide/mcp-tools/compare-runs.md","filePath":"user-guide/mcp-tools/compare-runs.md"}'),n={name:"user-guide/mcp-tools/compare-runs.md"};function o(d,s,h,l,p,k){return e(),a("div",null,[...s[0]||(s[0]=[t("",18)])])}const E=i(n,[["render",o]]);export{r as __pageData,E as default};