sparkforensics-server 0.6.0 → 0.8.1

package/vendor-core/finding-identity.js

@@ -0,0 +1,78 @@
+                                          
+
+/** Maps a finding's location in one run to a label shared by both runs. A stage or execution that
+ * pairs with one in the other run gets the same label on both sides; one that pairs with nothing
+ * gets a label no other run's location can equal. */
+                                 
+                                 
+                                         
+ 
+
+/** The finding's rule, or its type when the detector emits no rule. */
+export function findingRule(finding         )         {
+  return 'rule' in finding && typeof finding.rule === 'string' ? finding.rule : finding.type;
+}
+
+/** The finding's band, `unknown` when the impact estimate could not grade it. */
+export function findingBand(finding         )         {
+  return finding.impactBand ?? 'unknown';
+}
+
+// Location: stage, else SQL execution, else audited config property, else the whole run.
+function findingLocation(finding         , locator                )         {
+  if (finding.stageId != null) return `stage:${locator.stage(finding.stageId)}`;
+  if ('executionId' in finding && typeof finding.executionId === 'number') return `execution:${locator.execution(finding.executionId)}`;
+  if (finding.type === 'configAudit') return `property:${finding.property}`;
+  return 'run';
+}
+
+/** The identity of a finding across two runs: its type, rule and location. Never its value or its
+ * impact band, which both move from run to run for the same problem (`findingId` hashes the value,
+ * so it matches only within one run). */
+export function findingKey(finding         , locator                )         {
+  return `${finding.type}|${findingRule(finding)}|${findingLocation(finding, locator)}`;
+}
+
+                              
+                                                              
+                        
+                                                              
+                      
+                                                           
+                                                            
+ 
+
+function groupByKey(findings           , locator                )                         {
+  const groups = new Map                   ();
+  for (const finding of findings) {
+    const key = findingKey(finding, locator);
+    const group = groups.get(key);
+    if (group) group.push(finding); else groups.set(key, [finding]);
+  }
+  return groups;
+}
+
+/** Pairs two runs' findings by `findingKey`. A key several findings share (one detector firing per
+ * host on one run-level key, say) pairs one-to-one: same band first, then in catalog order, so only
+ * a count difference or a band no counterpart shares reads as a change. One diff feeds every
+ * comparison consumer: the verdict, the budgets and the dashboard. */
+export function diffFindings(
+  baseline           , candidate           , baselineLocator                , candidateLocator                ,
+)              {
+  const base = groupByKey(baseline, baselineLocator), cand = groupByKey(candidate, candidateLocator);
+  const diff              = { introduced: [], resolved: [], changed: [] };
+  for (const key of new Set([...base.keys(), ...cand.keys()])) {
+    const unpairedBase = [...(base.get(key) ?? [])], unpairedCand = [...(cand.get(key) ?? [])];
+    for (let i = unpairedBase.length - 1; i >= 0; i--) {
+      const j = unpairedCand.findIndex((f) => findingBand(f) === findingBand(unpairedBase[i]));
+      if (j < 0) continue;
+      unpairedBase.splice(i, 1);
+      unpairedCand.splice(j, 1);
+    }
+    const paired = Math.min(unpairedBase.length, unpairedCand.length);
+    for (let i = 0; i < paired; i++) diff.changed.push({ baseline: unpairedBase[i], candidate: unpairedCand[i] });
+    diff.resolved.push(...unpairedBase.slice(paired));
+    diff.introduced.push(...unpairedCand.slice(paired));
+  }
+  return diff;
+}

package/vendor-core/finding-presentation.js

@@ -8,7 +8,7 @@
 // detectors.ts is type-only, so it is erased at build time. A detector's scope, order and emits
 // list stay on its DETECTORS entry; renderers get them through detectorInfoByType().
                                                    
-                                                                  
+                                                                                                
                                                          
 
                                                              
@@ -30,6 +30,12 @@
 /** A share threshold as captions and caveats state it: 0.005 -> "0.5%", never float noise like 7.000000000000001%. */
 export const shareLabel = (share        )         => `${Math.round(share * 1e6) / 1e4}%`;
 
+/** `n.toLocaleString('en-US')` for a whole number, without loading ICU (about 10 ms the first time it is
+ * used), which keeps the CLI's startup off that cost. Other values take the locale path. */
+function groupThousands(n        )         {
+  return Number.isSafeInteger(n) ? String(n).replace(/\B(?=(\d{3})+$)/g, ',') : n.toLocaleString('en-US');
+}
+
 // Whether the detector found `key` already logged on for this run. Its switchFix (detectors.ts)
 // then worded the row's own text for that case and left the property out of the remediation, so
 // a generic line reads the same decision and never recommends a switch the row says is on.
@@ -38,6 +44,13 @@ function switchAlreadyOn(finding                                 , key        )
   return finding.remediation != null && !finding.remediation.some((r) => r.kind === 'conf' && r.key === key);
 }
 
+// The broadcast threshold properties a broadcast-sizing row's remediation names: the adaptive one when
+// it governed the query, else (and for a row with none) spark.sql.autoBroadcastJoinThreshold.
+function broadcastThresholdKeyOf(f                                 )         {
+  const keys = (f.remediation ?? []).filter((r)                       => r.kind === 'conf').map((r) => r.key);
+  return keys.length ? keys.join(' or ') : 'spark.sql.autoBroadcastJoinThreshold';
+}
+
 // The properties an idle-capacity finding lowers once dynamic allocation is on, worded as its row
 // does: the executor cap, and the floor when the row's remediation lowers it too.
 function idleCapacityLowering(f                                 )         {
@@ -45,28 +58,65 @@ function idleCapacityLowering(f                                 )         {
   return ` by lowering spark.dynamicAllocation.maxExecutors${lowersFloor ? ' and spark.dynamicAllocation.minExecutors' : ''}`;
 }
 
+// What a shuffle-reading stage's partition-count advice names, read from the row's remediation: the
+// property ('property', also for a finding with no remediation), AQE's coalescing settings ('aqe',
+// which leave spark.sql.shuffle.partitions out), or the stage's own repartition(n) ('code').
+function partitionAdviceKind(f                                 )                              {
+  if (f.remediation == null || f.remediation.some((r) => r.kind === 'conf' && r.key === 'spark.sql.shuffle.partitions')) return 'property';
+  if (f.remediation.some((r) => r.kind === 'conf' && r.key.startsWith('spark.sql.adaptive.'))) return 'aqe';
+  return f.remediation.some((r) => r.kind === 'code') ? 'code' : 'property';
+}
+
+// The skew-join line per AQE case, with no instance data (numbers, config values).
+const AQE_SKEW_GENERIC                                        = {
+  split: 'AQE skew-join handling already split the skewed partitions, so the imbalance that remains is not join skew: look for a GC pause, a slow host or an expensive key.',
+  evenReads: 'The shuffle reads are even, so the slow tail is not partition-size skew and AQE has nothing to split: look for a GC pause, a slow host or an expensive key.',
+  belowThreshold: 'The largest partition is under what AQE treats as skewed: lower the skew threshold or factor for this query.',
+  planShape: 'An operator sits between the join and its shuffle, so AQE skew-join handling cannot apply: salt the key or repartition on a better key.',
+  userRepartition: 'An explicit repartition feeds the join, so AQE leaves its shuffle alone: drop the repartition, or salt the key.',
+  joinType: 'The join type does not let AQE split the skewed side: put the skewed table on a splittable side, or salt the key.',
+  extraShuffle: 'AQE skipped the split because it would add a shuffle: set spark.sql.adaptive.forceOptimizeSkewedJoin to true if that shuffle is cheaper than the tail, or salt the key.',
+  notSplit: 'AQE did not split the skewed partition and the log does not say why: salt the key or repartition on a better key.',
+};
+// Before Spark 3.3 there is no forceOptimizeSkewedJoin, so an extraShuffle row carries a code fix.
+const AQE_SKEW_EXTRA_SHUFFLE_NO_FORCE = 'AQE skipped the split because it would add a shuffle: salt the key or repartition on a better key.';
+
 const SKEW_JOIN_KEY = 'spark.sql.adaptive.skewJoin.enabled';
 const SKEW_JOIN_ALREADY_ON = 'AQE skew-join handling is already on, so salt the key or repartition on a better key.';
 const SKEW_JOIN_AQE_OFF = 'AQE is off, so enable it (spark.sql.adaptive.enabled) for skew-join handling to apply; otherwise salt the key or repartition on a better key.';
 
 // The skew-join generic line, worded per the row's remediation: AQE logged off, switch already on, or neither.
-function skewJoinGeneric(f                                                      , unset        )         {
+function skewJoinGeneric(f                                                                             , unset        )         {
   if (f.origin === 'inputScan') return 'Uneven input files: compact small files or split large ones (lower spark.sql.files.maxPartitionBytes).';
   if (f.origin === 'other') return 'Work is uneven across tasks: salt the key or repartition on a better key.';
+  if (f.aqeSkew === 'extraShuffle' && !f.remediation?.some((r) => r.kind === 'conf')) return AQE_SKEW_EXTRA_SHUFFLE_NO_FORCE;
+  if (f.aqeSkew != null) return AQE_SKEW_GENERIC[f.aqeSkew];
   if (f.remediation?.some((r) => r.kind === 'conf' && r.key === 'spark.sql.adaptive.enabled')) return SKEW_JOIN_AQE_OFF;
   return switchAlreadyOn(f, SKEW_JOIN_KEY) ? SKEW_JOIN_ALREADY_ON : unset;
 }
+/** One line on what a straggler finding's slow tasks lost their time to, for the widget row; null
+ * when the log gave no cause (the finding then only knows their duration). */
+export function stragglerCauseSummary(f                                                                               )                {
+  const share = f.causeSharePct != null ? ` (${f.causeSharePct}% of their extra time)` : '';
+  switch (f.cause) {
+    case 'data': return `The slow tasks read more data${share}`;
+    case 'gc': return `GC${share}`;
+    case 'fetchWait': return `Waiting on shuffle fetches${share}`;
+    case 'host': return `Tasks piled on ${f.host ?? 'one host'}${share}`;
+    case 'unexplained': return 'Not data volume, GC, fetch wait or one host';
+    default: return null;
+  }
+}
+
 const DYNAMIC_ALLOCATION_KEY = 'spark.dynamicAllocation.enabled';
 
-// The four configAudit DETECTORS entries share this row, one per audited property.
+// The three configAudit DETECTORS entries share this row, one per audited property.
 const CONFIG_AUDIT_PRESENTATION                                     = {
   name: 'config audit',
   tag: 'CFG',
   thresholdSummary: () => 'a Spark conf value outside the recommended range',
   actionLabel(f) {
     switch (f.property) {
-      case 'spark.shuffle.service.enabled': return 'Enable shuffle service';
-      case 'spark.dynamicAllocation.minExecutors': return 'Fix autoscaling bounds';
       case 'spark.dynamicAllocation.maxExecutors': return 'Set max executors';
       case 'spark.serializer': return 'Switch to Kryo';
       case 'spark.executor.memoryOverhead': return 'Raise memory overhead';
@@ -75,11 +125,9 @@ const CONFIG_AUDIT_PRESENTATION                                     = {
   },
   genericRecommendation(f) {
     switch (f.property) {
-      case 'spark.shuffle.service.enabled': return 'Set spark.shuffle.service.enabled=true so shuffle data survives executor removal.';
-      case 'spark.dynamicAllocation.minExecutors': return 'Set the minimum executor bound at or below the maximum.';
       case 'spark.dynamicAllocation.maxExecutors': return 'Set spark.dynamicAllocation.maxExecutors to cap cluster growth.';
       case 'spark.serializer': return 'Consider spark.serializer=org.apache.spark.serializer.KryoSerializer for faster, smaller buffers.';
-      case 'spark.executor.memoryOverhead': return 'Raise executor memoryOverhead above Spark\'s default floor to avoid off-heap OOM-kills.';
+      case 'spark.executor.memoryOverhead': return 'Raise executor memoryOverhead above the default Spark would have computed to avoid off-heap OOM-kills.';
     }
     return undefined;
   },
@@ -98,7 +146,7 @@ export const FINDING_PRESENTATION
   skew: {
     name: 'task skew',
     tag: 'SKEW',
-    thresholdSummary: (t) => `P95 task time over ${t.ratioWarn}× the median (the longest task on stages under ${t.minTasksForP95} tasks)`,
+    thresholdSummary: (t) => `P95 task time over ${t.ratioWarn}× the median (the longest task on stages under ${t.minTasksForP95} tasks), and the slow tasks read correspondingly more data`,
     actionLabel: () => 'Fix task skew',
     genericRecommendation: (f) => skewJoinGeneric(f,
       'For join-driven skew, enable AQE skew-join handling (spark.sql.adaptive.skewJoin.enabled); otherwise salt the key or repartition on a better key.'),
@@ -129,9 +177,14 @@ export const FINDING_PRESENTATION
     tag: 'TINY',
     thresholdSummary: (t) => `${t.minTasks}+ tasks with a median of ${t.maxP50}ms or less and a P95 of ${t.maxP95}ms or less`,
     actionLabel: () => 'Coalesce small tasks',
-    genericRecommendation: (f) => (f.reads != null && f.reads !== 'shuffle'
-      ? 'Scheduler overhead may dominate: coalesce down to fewer, larger tasks.'
-      : 'Scheduler overhead may dominate: lower spark.sql.shuffle.partitions, or coalesce down to fewer, larger tasks.'),
+    genericRecommendation(f) {
+      if (f.reads != null && f.reads !== 'shuffle') return 'Scheduler overhead may dominate: coalesce down to fewer, larger tasks.';
+      switch (partitionAdviceKind(f)) {
+        case 'aqe': return 'Scheduler overhead may dominate: AQE already coalesced the shuffle, so set spark.sql.adaptive.coalescePartitions.parallelismFirst to false or raise spark.sql.adaptive.advisoryPartitionSizeInBytes, or coalesce down to fewer, larger tasks.';
+        case 'code': return "Scheduler overhead may dominate: this stage's own repartition(n) or RDD parallelism sized it, so lower that count or coalesce down to fewer, larger tasks.";
+        default: return 'Scheduler overhead may dominate: lower spark.sql.shuffle.partitions, or coalesce down to fewer, larger tasks.';
+      }
+    },
   },
 
   shuffle: {
@@ -180,9 +233,15 @@ export const FINDING_PRESENTATION
     thresholdSummary: (t) => `single-task disk spill above ${t.singleTaskDiskGiB} GiB`,
     actionLabel: () => 'Reduce spill',
     // The skew/volume classification isn't a Finding field, so one sentence covers both.
-    genericRecommendation: (f) => (f.reads != null && f.reads !== 'shuffle'
-      ? 'If the spill is skew-driven, fix task skew first: adding memory will not help. Otherwise increase executor memory or process less data per task.'
-      : 'If the spill is skew-driven, fix task skew first: adding memory will not help. Otherwise raise spark.sql.shuffle.partitions or increase executor memory.'),
+    genericRecommendation(f) {
+      const skewFirst = 'If the spill is skew-driven, fix task skew first: adding memory will not help. Otherwise';
+      if (f.reads != null && f.reads !== 'shuffle') return `${skewFirst} increase executor memory or process less data per task.`;
+      switch (partitionAdviceKind(f)) {
+        case 'aqe': return `${skewFirst} lower spark.sql.adaptive.advisoryPartitionSizeInBytes so AQE's merged partitions are smaller, or increase executor memory.`;
+        case 'code': return `${skewFirst} raise this stage's own partition count (its repartition(n) or RDD parallelism), or increase executor memory.`;
+        default: return `${skewFirst} raise spark.sql.shuffle.partitions or increase executor memory.`;
+      }
+    },
   },
 
   gc: {
@@ -220,7 +279,7 @@ export const FINDING_PRESENTATION
   slowHost: {
     name: 'slow executor host',
     tag: 'HOST',
-    thresholdSummary: (t) => `a host ${t.ratioWarn}× slower than its peers by mean task time (per-executor figures from ${t.ratioTiers[0]}×)`,
+    thresholdSummary: (t) => `a host ${t.ratioWarn}× slower than its peers by mean task time (per-executor figures from ${t.ratioTiers[0]}×, and only when the stage's own task-time spread cannot explain the gap)`,
     actionLabel(f) {
       if (f.variant === 'durationShare') return 'Fix data locality';
       if (f.variant === 'multiDim') return 'Investigate degraded executor';
@@ -240,18 +299,28 @@ export const FINDING_PRESENTATION
     tag: 'SLOW',
     thresholdSummary: () => 'a stage running far longer than its peers, not attributable to a single slow host',
     actionLabel: () => 'Profile slow stage',
-    genericRecommendation: (f) => f.reads === 'input'
-      ? 'Often too few or too uneven input partitions: check input file sizes and lower spark.sql.files.maxPartitionBytes, or look for a large per-task data volume driving heavy spill.'
-      : f.reads === 'other'
-        ? 'Check what the stage computes and for a large per-task data volume driving heavy spill.'
-        : 'Often a partition-count problem: raise parallelism via spark.sql.shuffle.partitions or spark.default.parallelism, or check for a large per-task data volume driving heavy shuffle and spill.',
+    genericRecommendation(f) {
+      if (f.reads === 'input') return 'Often too few or too uneven input partitions: check input file sizes and lower spark.sql.files.maxPartitionBytes, or look for a large per-task data volume driving heavy spill.';
+      if (f.reads === 'other') return 'Check what the stage computes and for a large per-task data volume driving heavy spill.';
+      const spill = 'or check for a large per-task data volume driving heavy shuffle and spill.';
+      switch (partitionAdviceKind(f)) {
+        case 'aqe': return `Often a partition-count problem: AQE coalesced the shuffle, so lower spark.sql.adaptive.advisoryPartitionSizeInBytes to get more tasks, ${spill}`;
+        case 'code': return `Often a partition-count problem: raise this stage's own partition count (its repartition(n) or RDD parallelism), ${spill}`;
+        default: return `Often a partition-count problem: raise spark.sql.shuffle.partitions, ${spill}`;
+      }
+    },
   },
   straggler: {
     name: 'straggling task',
     tag: 'STRAG',
-    thresholdSummary: () => 'one or more tasks finishing far after the rest of their stage',
+    thresholdSummary: () => 'one or more tasks finishing far after the rest of their stage, for a reason other than reading more data',
     actionLabel: () => 'Fix stragglers',
-    genericRecommendation: (f) => `Rule out a GC pause or a slow shuffle fetch before assuming a hardware issue. If uneven data is the cause: ${skewJoinGeneric(f, 'for join-driven skew, enable AQE skew-join handling (spark.sql.adaptive.skewJoin.enabled); otherwise salt the key or repartition on a better key.')}`,
+    genericRecommendation: (f) => f.cause === 'data' ? `Uneven data volume drives the slow tasks: ${skewJoinGeneric(f, 'for join-driven skew, enable AQE skew-join handling (spark.sql.adaptive.skewJoin.enabled); otherwise salt the key or repartition on a better key.')}`
+      : f.cause === 'gc' ? 'GC accounts for most of the slow tasks\' extra time: reduce object creation, use primitive types, avoid UDFs, increase executor memory.'
+      : f.cause === 'fetchWait' ? 'Waiting on shuffle fetches accounts for most of the slow tasks\' extra time: look for a slow or overloaded node serving shuffle blocks, executors lost mid-stage, or reducers fetching many small blocks.'
+      : f.cause === 'host' ? 'Most slow tasks ran on one host: check what it was running, and consider enabling spark.speculation to relaunch a lagging task automatically.'
+      : f.cause === 'unexplained' ? 'The slow tasks read no more data than the median task, and GC, shuffle fetch wait and one slow host do not account for their time: look at per-record cost (UDFs, regular expressions, a call out per row).'
+      : 'Nothing in the log attributes the slow tasks to data volume, GC, shuffle fetch wait or one host: check their input sizes, GC time and hosts before choosing a fix.',
   },
   speculationWaste: {
     name: 'speculation waste',
@@ -279,8 +348,8 @@ export const FINDING_PRESENTATION
         case 'idleCores': return 'Reduce idle cores';
         case 'wasteModel': return 'Right-size executor memory';
         case 'memoryBand':
-          if (f.dataUnavailable) return 'Enable memory metrics';
-          return f.rule === 'heapNearCapacity' ? 'Increase executor memory' : 'Reduce executor memory';
+          if (f.dataUnavailable) return 'Executor heap peaks unavailable';
+          return 'Reduce executor memory';
       }
       return undefined;
     },
@@ -292,9 +361,7 @@ export const FINDING_PRESENTATION
         case 'wasteModel': return 'Review spark.executor.memory and executor count.';
         case 'memoryBand':
           if (f.dataUnavailable) return undefined;
-          return f.rule === 'heapNearCapacity'
-            ? 'Memory may be too small: raise spark.executor.memory to avoid OOM/spill.'
-            : 'Memory may be over-provisioned: consider reducing spark.executor.memory for cost savings.';
+          return 'Memory may be over-provisioned: consider reducing spark.executor.memory for cost savings.';
       }
       return undefined;
     },
@@ -373,14 +440,30 @@ export const FINDING_PRESENTATION
       ? 'Repartition or coalesce before writing to raise the average file size.'
       : 'Compact the upstream output so fewer, larger files are produced.'),
   },
+  pythonUdf: {
+    name: 'row-at-a-time Python UDF',
+    tag: 'PLAN',
+    thresholdSummary: (t) => `over ${t.minBytesSent / 1048576} MiB sent to Python workers by stages running over ${t.minStageMs / 1000} s`,
+    actionLabel: () => 'Vectorize Python UDF',
+    genericRecommendation: () => 'Use Arrow-optimized Python UDFs (spark.sql.execution.pythonUDF.arrow.enabled, Spark 3.4 and later) or a pandas UDF instead of a row-at-a-time Python UDF.',
+  },
+  nestedLoopJoin: {
+    name: 'nested loop join',
+    tag: 'PLAN',
+    thresholdSummary: (t) => `a nested-loop or cartesian join with over ${groupThousands(t.minOutputRows)} output rows, at least ${t.minExpansion}x its larger input`,
+    actionLabel: (f) => (f.condition == null ? 'Confirm cross join' : 'Add an equi-join key'),
+    genericRecommendation: (f) => (f.condition == null
+      ? 'Confirm the cross join is intended, or add a join key so the rows are matched instead of multiplied.'
+      : 'Add an equi-join key so Spark can use a hash or sort-merge join; for a range condition, bucket the range and join on the bucket as well.'),
+  },
   underBroadcast: {
     name: 'missed broadcast join',
     tag: 'PLAN',
-    thresholdSummary: () => 'a join below the configured size floor that skipped broadcast',
+    thresholdSummary: (t) => `a join side its type can broadcast, between ${t.minSmallerSideBytes / 1048576} MiB and ${t.overBroadcastBytes / 1073741824} GiB, that skipped broadcast`,
     actionLabel: () => 'Use broadcast join',
     genericRecommendation: (f) => (f.broadcastThreshold === 'notLimiting'
-      ? 'The threshold already admits the smaller side, so it is not what stopped the broadcast: consider a broadcast() hint or collecting table statistics.'
-      : 'This could have been a broadcast join: consider a broadcast() hint or raising spark.sql.autoBroadcastJoinThreshold.'),
+      ? 'The threshold already admits the build side, so it is not what stopped the broadcast: consider a broadcast() hint or collecting table statistics.'
+      : `This could have been a broadcast join: consider a broadcast() hint or raising ${broadcastThresholdKeyOf(f)}.`),
   },
   overBroadcast: {
     name: 'oversized broadcast join',
@@ -389,9 +472,9 @@ export const FINDING_PRESENTATION
     actionLabel: () => 'Fix oversized broadcast',
     genericRecommendation: (f) => (f.broadcastThreshold === 'notLimiting'
       ? 'The configured threshold is below this broadcast, so remove the broadcast() hint that forced it.'
-      : switchAlreadyOn(f, 'spark.sql.autoBroadcastJoinThreshold')
+      : f.broadcastThreshold === 'disabled'
       ? 'Automatic broadcast is already disabled, so remove the broadcast() hint that forced it.'
-      : 'Check for a misapplied broadcast hint or a misconfigured spark.sql.autoBroadcastJoinThreshold.'),
+      : `Check for a misapplied broadcast hint or a misconfigured ${broadcastThresholdKeyOf(f)}.`),
   },
 };
 

package/vendor-core/finding-types.js

@@ -88,12 +88,20 @@
                        
  
 
-// ── Per-stage detectors ─────────────────────────────────────────────────────
-
 /** What a skewed stage reads, which decides the fix: 'shuffleJoin' (a shuffle feeding a join, where
  * AQE skew-join handling applies), 'inputScan' (uneven input files) or 'other'. */
                                                                
 
+/** What AQE skew-join handling did for a 'shuffleJoin' stage, read from the final plan and the
+ * effective conf: 'split' (it split the skewed partition, so the rest is not join skew),
+ * 'evenReads' (the shuffle reads are even, so no partition is skewed for AQE to split),
+ * 'belowThreshold' (the partition is under the effective skew threshold or factor), 'planShape' (an
+ * operator sits between the join and its shuffle), 'userRepartition' (the shuffle is an explicit
+ * repartition), 'joinType' (the join type does not let AQE split the skewed side),
+ * 'extraShuffle' (splitting would add a shuffle for the operator above the join) or 'notSplit'
+ * (nothing in the log explains it). */
+                                                                                                                                                
+
 /** What a stage reads, by the dominant side: a shuffle, input files, or neither. */
                                                        
 
@@ -103,8 +111,23 @@
  * enough, so the stage's own repartition(n) or RDD parallelism is). */
                                                                                             
 
+/** Why a stage's slow tail is slow (attributeTail in stage-quantiles.ts). 'data': the slow tasks
+ * read far more than the median task, so run time follows data volume. 'gc', 'fetchWait' and
+ * 'host': the tail's extra time is GC, shuffle fetch wait, or tasks piled on one host.
+ * 'unexplained': the slow tasks read no more than the median and none of those accounts for their
+ * time. 'unattributed': the stage has no data volume to compare and what data, GC, fetch wait and
+ * host do not explain is the largest share (or the stage has no tail attribution), so only the
+ * duration is known. */
+                                                                                              
+
                                
                       
+                                                                                                     
+                        
+                                                                                                          
+                    
+                                                                                   
+                     
  
                                                                             
 
@@ -123,8 +146,9 @@
 
                                           
                                                                                 
-                                                    
+                                                                    
                       
+                        
                                                                                                            
                                  
  
@@ -155,6 +179,10 @@
                       
                                                                                                 
                         
+                                                                                                  
+                                                                                          
+                         
+                     
  
                                                                                         
 
@@ -185,11 +213,23 @@
                                                                                         
 
                                     
-                        
+                                                                                                 
+                                  
                            
                          
-                                                                                     
+                                                                                              
+                              
                       
+                        
+                                                                                                     
+                    
+                                                                             
+                         
+                                                                                            
+                
+                     
+                                                                                              
+                  
  
                                                                                            
 
@@ -211,8 +251,6 @@
                      
  
                                                                                         
-
-// ── App-level detectors ─────────────────────────────────────────────────────
 
                                                          
 // valueText is always 'missing': the ApplicationEnd event the log lacks.
@@ -225,7 +263,7 @@
                                                                                            
 
                                       
-                                                                                               
+                                                                      
                                    
  
                                                                                                 
@@ -239,21 +277,24 @@
 
                                             
                                                      
-                                                             
-                                                    
+                                                              
+                               
+                                                                          
                       
-                                                               
+                                                                                                 
                 
                                                               
                             
  
                                                                                                                   
                                                                                          
-                                                                                         
+                                                                                                  
                             
                                      
-                         
                           
+                                                                                                         
+                         
+                           
  
 
                                            
@@ -304,17 +345,13 @@
                           
  
                                                                                                           
-
-// ── Config-scope detectors ──────────────────────────────────────────────────
 
                                       
                    
  
-// valueText is the audited property's current value, or a note that it is unset or inverted.
+// valueText is the audited property's current value, or a note that it is unset.
                                                                                               
 
-// ── SQL-scope (Plan Advisor) detectors ──────────────────────────────────────
-
                                
                       
                      
@@ -344,13 +381,41 @@
  
                                                                                                               
 
-/** How the effective spark.sql.autoBroadcastJoinThreshold relates to the finding: 'limits' (the
+                                                                
+                                                                                                
+                        
+                                                                           
+                                   
+                                                                         
+                          
+ 
+                                                                                                           
+/** A BroadcastNestedLoopJoin or CartesianProduct whose output is far larger than both inputs.
+ * `nodeName` is the operator, `joinType` the Spark join type (null when the plan line has none)
+ * and `condition` the join condition with expression ids removed (null for a join without one).
+ * `leftRows` and `rightRows` are the input row counts the executors reported, null for a
+ * CartesianProduct, which re-reads its inputs so their counts are not row counts. */
+                                                                     
+                                                           
+                          
+                           
+                     
+                          
+                           
+ 
+                                                                                                                          
+
+/** How the effective broadcast threshold (spark.sql.autoBroadcastJoinThreshold, or its adaptive counterpart under AQE) relates to the finding: 'limits' (the
  * property decided it, or is unknown), 'notLimiting' (already admits, or already below, the
  * broadcast, so something else decided it) or 'disabled' (-1). */
                                                                        
 
                                                                      
+                                                                            
                           
+                                                                                                       
+                   
+                              
                                           
  
                                                                                                                           
@@ -360,8 +425,6 @@
  
                                                                                                                        
 
-// ── Unions ──────────────────────────────────────────────────────────────────
-
 /** Public evidence fields per finding type: what a report row's `evidence` carries. */
                                      
                      
@@ -390,6 +453,8 @@
                                    
                                                      
                                  
+                               
+                                         
                                          
                                        
  
@@ -421,6 +486,8 @@
                       
                                
                      
+                    
+                         
                          
                          
 

package/vendor-core/format-utils.js

@@ -14,9 +14,9 @@ const BOTTLENECK_WIDGET                                   = {
   coldStart: 'executor-timeline', utilization: 'executor-timeline', speculationWaste: 'executor-timeline',
 }                                               ;
 
-// Cross-widget stage recurrence: how many distinct board widgets (skew+straggler on one stage
-// still count as one, task-skew) flag a stage. Computed once from the full catalog each widget
-// already receives.
+// Cross-widget stage recurrence: how many distinct widget groups (skew, slowHost and straggler
+// share task-skew) flag a stage. No production code calls it, and the group names in
+// BOTTLENECK_WIDGET are labels, not ids of rendered widgets.
 // `stageId` may be number|null|undefined: sql/config-scope findings never set it; `stageId == null`
 // below treats both the same.
 export function stageWidgetFrequency(catalog                                                )                      {
@@ -69,9 +69,7 @@ export function formatStageIdsLabel(stageIds          , maxShown         = DEFAU
 }
 
 /** Worst (lowest IMPACT_BAND_ORDER) impact band across findings, undefined when empty. Shared by
- * every widget that badges/colors a group of findings.
- * @param {{ impactBand: 'critical' | 'warning' | 'info' }[]} findings
- * @returns {'critical' | 'warning' | 'info' | undefined} */
+ * every widget that badges/colors a group of findings. */
 export function worstImpactBand(
   findings                                                   ,
 )                                              {
@@ -285,15 +283,16 @@ export function formatRawWaste(rawWaste                )         {
   }
 }
 
-// formatRawWaste/fmtMs round to a fixed precision (one decimal place, or
-// whole milliseconds below 1s), which can collapse a small but genuinely
-// nonzero value down to a formatted string that reads exactly like zero
-// (0.04 coreHours -> "0.0 core-h"). Checking the raw value against 0 misses
-// this; checking the *formatted* text against zero's own formatted text
-// catches it regardless of unit. The fractional group must consume the
-// entire decimal part (all zeros) before the terminator: otherwise a real
-// value like "0.5 core-h" leaves the "." unconsumed, and the terminator
-// char class excludes ".", so it correctly fails to match.
+/** A cost-only figure as core time. Task time summed over tasks (`ms`) is core time, and printing
+ * it as a duration beside wall-clock savings reads as run time it does not shorten. */
+export function asCoreTime(rawWaste                )                 {
+  return rawWaste.unit === 'ms' ? { ...rawWaste, unit: 'coreMs' } : rawWaste;
+}
+
+// True when a formatted figure reads as zero, including a small nonzero value the fixed rounding
+// collapsed (0.04 coreHours -> "0.0 core-h"). It tests the formatted text, so it holds for any unit.
+// The fractional group must consume the whole decimal part before the terminator, so "0.5 core-h"
+// does not match.
 export function readsAsZero(formatted        )          {
   return /^0(\.0+)?(?:[^0-9.]|$)/.test(formatted);
 }