sparkforensics-mcp

SparkForensics

你的 Spark 作业运行缓慢。SparkForensics 会告诉你原因，以及如何解决。

放入 Spark 事件日志，即可获取基于证据的分析，了解哪些阶段运行缓慢、原因是什么，以及如何修复。无需在你的集群上安装任何东西，而且不会有任何数据离开你的设备。

立即试用 →，分析你自己的事件日志。无需安装、无需账号、无需上传。阅读文档了解使用指南。

Spark 自带的 History Server 只提供原始指标。它不会告诉你第 14 阶段为何因倾斜的联接键而产生 40GB 溢写，也不会指出冷启动占用了作业三分之一的时间。SparkForensics 读取相同的事件日志，并将其转化为分析结果。

为什么选择 SparkForensics

• 数据会保留在你的设备上。拖入日志文件并查看仪表板；不会上传到任何地方。本地服务模式会添加一个轻量级 Node 配套程序，也可以从 Spark History Server 拉取运行记录。
• 事件日志会在 Web Worker 中流式读取并解析，不占用主线程，因此 240MB 以上（甚至数 GB）的 NDJSON 日志也不会让标签页卡住。
• 25 种分析类型涵盖倾斜、Shuffle、溢写、GC 压力、拖后腿任务、冷启动、缓存 / 内存利用率、自动扩缩容波动、作业 / 阶段失败和分区大小，还包括 SQL 计划顾问（重复子树、小文件、广播大小）和配置审计。所有检测器及其阈值都列在检测器表中。
• “优先修复这些问题”会根据每项分析结果预估的实际运行时间影响来排序，而不仅仅看严重程度，让你一眼找到最值得优先处理的问题。
• 运行对比（A/B）模式会对同一作业的两次运行进行结构化阶段匹配，并指出哪些阶段出现回退，而不是罗列所有差异。
• 每项分析结果都会记录日志能够和无法确认的内容，让你知道何时可以信任标记，何时应将其视为需要手动核查的提示。
• 无界面的 CLI（sparkforensics-analyze）会根据预算阈值（最长运行时间、倾斜、溢写、失败率等）评估一次运行，并在违反阈值时返回非零退出码，让回归问题可以导致构建失败。运行记录可以来自本地事件日志文件 / 目录；也可以通过 --shs-base-url 直接从 Spark History Server 获取。
• MCP 服务（sparkforensics-mcp）提供用于诊断、汇总和对比运行记录的工具，让大模型 Agent 可以直接调查一次运行。完整工具列表见 MCP 工具。
• 如果想让 analyze CLI 在每次 Spark 作业完成后自动运行，而不是手动执行，请参阅 sparkforensics-operator：这是一个 Airflow operator，可在作业的事件日志上运行 SparkForensics 并根据结果采取行动。

不同于需要集群端插件，或需要运行服务和大模型 Agent 的工具（Spark History Server MCP 工具），SparkForensics 无需在其他地方安装任何东西：只需事件日志和浏览器标签页即可。

开始使用

在本地运行仪表板：

npx sparkforensics-server

入门指南 介绍了它提供的功能、在线演示 这一替代方案，以及如何加载一次运行记录。若要开发 SparkForensics 本身，请参阅 开发。

要在不使用浏览器的情况下进行一次性检查（可作为 CI 流水线的门禁条件）：

npx -p sparkforensics-cli sparkforensics-analyze path/to/eventlog --max-runtime 3600000 --max-skew 3

此命令包含在 sparkforensics-cli 软件包中。也可以一次性安装： npm i -g sparkforensics-cli，然后直接运行 sparkforensics-analyze。 sparkforensics-analyze 别名软件包也可使用： npx sparkforensics-analyze。

这是一次针对预算阈值的无头运行。有关 HTML 导出、Spark History Server 获取、基线比较和脱敏的信息，请参阅下文的命令行 参考。 若要使用自己的阈值运行检测器检查，请参阅 调整检测器阈值。

开发

安装并运行

在代码检出目录中：

git clone [email protected]:shuffle-works/sparkforensics.git
cd sparkforensics
npm install
npm run dev

打开 Vite 输出的网址。要生成生产环境构建：运行 npm run build，然后使用 任意静态文件服务提供 dist/。资源 URL 使用相对路径，因此构建结果也能在 URL 子路径下运行。

注意： 应用必须通过 HTTP 提供：在 Chrome 中，file:// URL 会阻止 Web Worker 模块导入。

部署模式

此应用支持两种模式：

• 静态模式（例如 GitHub Pages 或任意普通文件服务）：对于单个事件日志，选择文件 是常规的浏览器本地加载方式。选择滚动日志文件夹仅适用于 eventlog_v2_* 目录。部署 npm run build 生成的 dist/ 内容。无法直接从 Spark History Server 获取数据：浏览器的 CORS 策略会阻止请求，静态主机也无法代理 请求。如果无法通过 History Server 加载，请改为选择本地事件日志文件。
• 本地服务模式是一种小型 Node 配套服务，可提供此应用并 代为从 Spark History Server 获取数据（服务器到服务器，因此不受浏览器 CORS 限制）。 适用于 SHS 位于 VPN 后面或未配置 CORS 的情况。

使用以下命令运行本地服务模式：

npx sparkforensics-server

默认情况下，它会监听 http://127.0.0.1:4173（可通过 --port 或 PORT 环境变量覆盖），并且仅绑定到 localhost。在 Chrome 中打开该 URL，然后 使用数据导入界面上的 从 Spark History Server 获取选项。此服务也会通过 /mcp 以可流式传输的 HTTP 方式提供 MCP 工具，供同一台机器上的客户端使用；请参阅 通过 HTTP 连接。

使用 History Server 获取数据，需要处于本地服务模式、运行该服务的机器能够访问 History Server，并且使用受支持的基础应用程序 ID（接受的完整格式列表请参阅入门指南）。 请将可选的 attempt 与基础应用程序 ID 分开输入。本地服务不会发送凭据，也不会 跟随上游重定向。可恢复错误会有意省略上游响应详情；请编辑字段或选择本地事件日志文件 以继续操作。

在代码检出目录中开发时，运行 npm run local-server 即可实现相同功能，无需发布或安装软件包。

服务配置

所有设置均有可用的默认值。端口（PORT 或 --port）和 SPARKFORENSICS_* 环境变量列于 服务配置。

SHS-proxy 路由测试夹具

/shs-proxy 路由（packages/core/src/proxy.js）由 packages/server/test/shs-proxy-fixture.test.js 覆盖，该测试属于常规的 npm run test:server 测试套件。它会从 dev/log-corpus/ 中的 spark-event-corpus-data git 子模块加载真实事件日志，并断言该路由会以有效 ZIP 文件的形式将其流式传回。此测试不需要 Docker、正在运行的 Spark 进程或正在运行的 History Server。

若要手动验证完整的“从 SHS 获取”界面流程，包括上游无法访问和找不到应用时的恢复状态，请将 npm run local-server 指向你有权限访问的真实 Spark History Server， 并使用其中的 从 Spark History Server 获取 折叠面板。对 /shs-proxy 的自动化测试使用 spark-event-corpus-data 日志，因此不需要 Docker 镜像或正在运行的 Spark 进程。

运行测试

npm test              # single run
npm run test:watch    # watch mode
npm test -- tests/finding-filter.test.js  # single file
npm run test:core     # packages/core: detectors, analyzer, parser, MCP tools
npm run test:cli      # packages/cli
npm run test:mcp      # packages/mcp
npm run test:server   # packages/server

命令行参考

除了快速开始中的基础预算检查外，同一个 sparkforensics-analyze CLI 还可执行其他一些任务。

为本次运行生成独立的 HTML 仪表板，而不是 JSON/Markdown 报告；无需服务器，即可通过 file:// 离线查看：

npx -p sparkforensics-cli sparkforensics-analyze path/to/eventlog --export-html path/to/output-dir

直接从 Spark History Server 获取本次运行，而不是读取本地文件 （不能与位置参数路径同时使用）：

npx -p sparkforensics-cli sparkforensics-analyze --shs-base-url http://history-server:18080 --app-id application_1234_0001 --max-skew 3

将候选运行与基准运行进行比较（A/B），并在出现性能回退或新增严重问题时让构建失败：

npx -p sparkforensics-cli sparkforensics-analyze path/to/candidate --baseline path/to/baseline --max-regression-pct 10 --fail-on-introduced critical

在一次调用中检查多个回退预算，并将多个候选运行与同一个基准运行进行比较（NDJSON，每个候选运行一行；基准运行只解析一次）：

npx -p sparkforensics-cli sparkforensics-analyze cand-1 cand-2 cand-3 --baseline base --regression-budget wallClock:10 --regression-budget gcTime:25

与存放在 Spark History Server 上的基准运行进行比较，候选运行可以来自本地文件，也可以来自 History Server；使用 --baseline-shs-base-url、 --baseline-app-id 和 --baseline-attempt-id（基准运行可以位于另一台服务器上）：

npx -p sparkforensics-cli sparkforensics-analyze --shs-base-url http://history-server:18080 --app-id application_1234_0002 --baseline-shs-base-url http://history-server:18080 --baseline-app-id application_1234_0001 --max-regression-pct 10

从一个 History Server 获取多个候选运行时，需重复指定 --app-id（--app-id <id>:<attempt> 用于指定一次尝试），并输出 NDJSON，每个候选运行一行。

有关 --budgets 文件、NDJSON 行字段和退出码规则，请参阅多个预算与多个候选运行。

在将输出分享给生成该输出的环境之外的人员之前，请对 URL 和路径中的应用 ID、应用名称、主机名、IP 地址和用户名进行脱敏。其他路径、表名和 SQL 文本保持原样；CI 指南 列出了 --redact 会脱敏和不会脱敏的内容：

npx -p sparkforensics-cli sparkforensics-analyze path/to/eventlog --redact

将输出的 findings 数组限定为特定影响等级、类型或阶段（recommendations/cleanChecks/notRunChecks 和摘要计数仍基于完整、未筛选的数据集）：

npx -p sparkforensics-cli sparkforensics-analyze path/to/eventlog --impact critical,warning --type stageSlowness --stage 12

其他预算标志可完善检查：--max-spill <gb>、 --max-failed-task-rate <pct> 和 --min-efficiency <pct>（繁忙核心时间： 执行器核心时间中用于运行任务的比例，即 100 减去仪表板中的未使用核心时间，而不是其中的效率指标）。对于非默认尝试， --attempt-id 与 --shs-base-url/--app-id 搭配使用； --regression-metric 用于选择 --max-regression-pct 检查的指标 （默认为 wallClock）；--conf-keys 和 --conf-redact-regex 用于调整 JSON 输出中 effectiveConf 区块的内容，该区块与 metrics 区块并列（两者均见 快速开始）； --format md 将输出切换为 Markdown（默认为 json）；--out <path> 将输出写入文件，而不是标准输出（其文件夹必须 存在，否则命令以 2 退出）。退出码： 0 通过，1 违反预算，2 用法错误（标志、参数或 --thresholds/--budgets 文件无效），3 预算无法得出结论（例如回退检查缺少 证据），4 无法读取或解析候选日志，5 无法读取或解析基准日志，6 内部错误。当 多种情况同时出现时，按 6、5、4、1、3、0 的顺序取最严重的退出码；对于 多个候选运行，这意味着取最严重的一行，而无法读取或解析的候选运行会在其对应行中给出 4。

**Node 版本：**已发布的 sparkforensics-cli、sparkforensics-mcp 和 sparkforensics-server 软件包会在发布时预先将随附的 TypeScript 转换为纯 JS，因此使用 npx 安装的版本只需要 Node >=18（参见各软件包的 engines 字段）。如果在检出代码中直接通过 packages/*/bin/ 运行这三个程序，并使用 packages/core/src/*.ts （monorepo 开发模式备用方案），则需要支持原生（无需标志）TypeScript 类型剥离的 Node 版本： Node 22 LTS 系列需 >=22.18.0，Node 23 及更高版本需 >=23.6.0。

了解更多

完整文档发布于 shuffle-works.github.io/sparkforensics/docs。

• 入门指南：阅读仪表板、比较运行结果、CI 和自动化
• 了解分析结果
• MCP 工具
• 检测器表格
• Worker 协议
• 流式处理／解析设计
• 组件布局

参与贡献

请参阅 CONTRIBUTING.md。

许可证

MIT