SPILL

Spill

Tasks run out of execution memory and write intermediate data to disk.

Outcome: Speed
Scope: Judged per stage
Usual fix: A change in the job code
CI gate: Budget flag --max-spill

An example finding

Where you see it

Dashboard

The SPILL tag marks it in the action region of the dashboard, among the widgets that rank a fix. Every affected stage is flagged, not only the worst.How to read it in the findings guide.

Agent (MCP)

An assistant can read this entry with the list_detectors tool and its background with get_finding_documentation. The call and the response below come from a real run of the MCP server.

Call

{
  "tool": "list_detectors",
  "arguments": {
    "type": "spill"
  }
}

Response

{
  "count": 1,
  "detectors": [
    {
      "type": "spill",
      "name": "spill",
      "tag": "SPILL",
      "tagSharedWith": [],
      "family": "speed",
      "pitch": "Tasks run out of execution memory and write intermediate data to disk.",
      "region": "action",
      "scope": "stage",
      "fixEffort": "code",
      "thresholdSummary": "single-task disk spill above 1 GiB",
      "detectors": [
        {
          "detector": "spill",
          "version": 1,
          "thresholds": {
            "singleTaskDiskGiB": 1,
            "singleTaskMemGiB": 4,
            "highDiskGiB": 1,
            "highTaskDiskMB": 512,
            "highMemGiB": 4,
            "medDiskMB": 256,
            "medMemGiB": 1,
            "skewRatio": 5,
            "skewDiskFloorMB": 128,
            "skewMemFloorMB": 256,
            "skewMinTasks": 10,
            "stageFloorPct": 0.005,
            "wideRowRatio": 10,
            "wideRowMinInputMB": 64,
            "peakNearShareRatio": 0.8
          }
        }
      ],
      "pages": {
        "catalog": "docs/detectors/spill.html",
        "guide": "docs/user-guide/understanding-findings.html#spill"
      },
      "tuning": {
        "kind": "page",
        "anchor": "#bottleneck-spill",
        "path": "docs/tuning-reference/bottleneck-spill.html#bottleneck-spill"
      },
      "gate": {
        "cliFlag": "--max-spill",
        "airflowParam": "max_spill_gb"
      }
    }
  ]
}

get_finding_documentation call

{
  "tool": "get_finding_documentation",
  "arguments": {
    "type": "spill"
  }
}

Its response, with each Markdown body replaced by its length

{
  "type": "spill",
  "name": "Spill",
  "detectionDoc": {
    "tag": "SPILL",
    "title": "Memory and disk spill",
    "content": "<3838 characters of Markdown>"
  },
  "tuningDoc": {
    "anchor": "#bottleneck-spill",
    "title": "Memory / Disk Spill",
    "content": "<8081 characters of Markdown>"
  }
}

CI (CLI)

List this entry from the command line. The output below is a real run of the command. Budgets and exit codes are in the CI guide.

sparkforensics-analyze detectors --type spill --format md

# Detectors (1)

## Speed

| Tag | Type | Scope | Fix | Gate | What it finds |
| --- | --- | --- | --- | --- | --- |
| SPILL | `spill` | stage | code | `--max-spill` | Tasks run out of execution memory and write intermediate data to disk. |

Report only this finding type for a run with --type:

sparkforensics-analyze <event-log> --type spill --impact critical,warning,info

Fail the build when the run breaches a budget for it:

sparkforensics-analyze <event-log> --max-spill <n>

Airflow

The operator takes the budget as the max_spill_gb parameter.

check_spark_job = SparkForensicsOperator(
    task_id="check_spark_job",
    log_source=...,
    backend=SubprocessAnalyzeHook(),
    max_spill_gb=...,  # your budget
)

The operator works per run, and its summary counts findings per impact band. See the operator for its parameters.

How it is measured

Thresholds

Single-task disk spill above 1 GiB.

spill version 1

Threshold	Default
`singleTaskDiskGiB`	1
`singleTaskMemGiB`	4
`highDiskGiB`	1
`highTaskDiskMB`	512
`highMemGiB`	4
`medDiskMB`	256
`medMemGiB`	1
`skewRatio`	5
`skewDiskFloorMB`	128
`skewMemFloorMB`	256
`skewMinTasks`	10
`stageFloorPct`	0.005
`wideRowRatio`	10
`wideRowMinInputMB`	64
`peakNearShareRatio`	0.8

Each rule's impact bands and fixed fallbacks are in the threshold tables.

Override a default per run with --thresholds; see Tuning detector thresholds.

Docs

This finding has its own tuning page: Spark tuning reference.
Findings guide: SPILL in Understanding findings.