spark-operations-cli

遥测 — 强制要求。 每次 api.fabric.microsoft.com 调用都必须携带 x-ms-fabric-skill: spark-operations-cli（az rest：--headers "x-ms-fabric-skill=spark-operations-cli"）， 包括每次 LRO 轮询、fabric_lro 和重试。代码片段中省略了此项——仍须添加。

检查更新 — 每个会话一次（强制要求） 首次在某个会话中使用此技能时，必须先运行 check-updates 技能，再继续操作。

• GitHub Copilot CLI / VS Code：调用 check-updates 技能。
• Claude Code / Cowork / Cursor / Windsurf / Codex：比较本地与远程的 package.json 版本。
• 如果本会话较早时已执行过检查，则跳过。

重要说明

1. 若要根据工作区名称查找工作区详细信息（包括其 ID）：列出所有工作区，然后使用 JMESPath 进行筛选
2. 若要根据工作区 ID、项类型和项名称查找项详细信息（包括其 ID）：列出该工作区中该类型的所有项，然后使用 JMESPath 进行筛选
3. 技能区分：spark-operations-cli 用于对现有作业和会话进行只读分流与诊断。若要创建笔记本、运行新作业或进行 Spark 开发，请使用 spark-authoring-cli。若要进行交互式 PySpark 分析并创建 Livy 会话，请使用 spark-consumption-cli。

Spark Operations — CLI 技能

此技能使用 Fabric REST API 和 CLI 工具（az rest），诊断 Microsoft Fabric Spark 作业故障、Livy 会话健康状况和性能瓶颈。所有诊断操作均为只读；清理会话（例如停止僵尸会话）需要用户明确确认。若要进行 Spark 开发和笔记本创作，请使用 spark-authoring-cli。若要进行交互式 PySpark 分析，请使用 spark-consumption-cli。

目录

目录按用途分组。排查正在发生的故障时，请从 诊断工作流 开始；前面的部分是基础参考资料。

1. Fabric 基础知识（概念）

任务	参考资料	备注
Fabric 拓扑与关键概念	COMMON-CORE.md § Fabric Topology & Key Concepts
环境 URL	COMMON-CORE.md § Environment URLs
身份验证与令牌获取	COMMON-CORE.md § Authentication & Token Acquisition	受众错误会导致 401；遇到任何身份验证问题前请先阅读
核心控制平面 REST API	COMMON-CORE.md § Core Control-Plane REST APIs
分页	COMMON-CORE.md § Pagination
长时间运行的操作（LRO）	COMMON-CORE.md § Long-Running Operations (LRO)
速率限制与流量控制	COMMON-CORE.md § Rate Limiting & Throttling
作业执行	COMMON-CORE.md § Job Execution
容量管理	COMMON-CORE.md § Capacity Management
常见问题与故障排除	COMMON-CORE.md § Gotchas & Troubleshooting
最佳实践	COMMON-CORE.md § Best Practices

2. CLI 设置与身份验证

任务	参考	备注
工具选择依据	COMMON-CLI.md § 工具选择依据
在 Fabric 中查找工作区和项	COMMON-CLI.md § 在 Fabric 中查找工作区和项	必读 — 请先阅读链接内容 [用于根据名称查找工作区 ID，或根据名称、项类型和工作区 ID 查找项 ID]
身份验证操作指南	COMMON-CLI.md § 身份验证操作指南	az login 流程和令牌获取
通过 az rest 调用 Fabric 控制平面 API	COMMON-CLI.md § 通过 az rest 调用 Fabric 控制平面 API	始终传入 --resource https://api.fabric.microsoft.com，否则 az rest 会失败
分页模式	COMMON-CLI.md § 分页模式
长时间运行操作（LRO）模式	COMMON-CLI.md § 长时间运行操作（LRO）模式
注意事项与故障排除（CLI 专用）	COMMON-CLI.md § 注意事项与故障排除（CLI 专用）	az rest 受众、Shell 转义、令牌过期
快速参考：az rest 模板	COMMON-CLI.md § 快速参考：az rest 模板
快速参考：令牌受众 / CLI 工具矩阵	COMMON-CLI.md § 快速参考：令牌受众 ↔ CLI 工具矩阵	各服务对应的 --resource 和工具

3. Spark 会话、笔记本和作业（后台）

任务	参考	备注
Livy 会话管理	SPARK-CONSUMPTION-CORE.md § Livy 会话管理	会话创建、状态、生命周期、终止
交互式数据探索	SPARK-CONSUMPTION-CORE.md § 交互式数据探索	语句执行、输出检索、数据发现
笔记本执行与作业管理	SPARK-AUTHORING-CORE.md § 笔记本执行与作业管理

4. Spark 监控 API（主要分诊入口）

任务	参考	说明
Spark 监控 API 概览	SPARK-MONITORING-CORE.md § 概览	GA 监控 API — 无需活动会话
工作区和项级会话列表	SPARK-MONITORING-CORE.md § 工作区和项级会话列表	列出工作区中的 Spark 应用，并支持筛选
Spark Advisor API	SPARK-MONITORING-CORE.md § Spark Advisor API	重点 — 自动检测数据倾斜、任务错误并提供建议
开源 Spark History Server API	SPARK-MONITORING-CORE.md § 开源 Spark History Server API	通过 REST 获取作业、阶段、执行器和 SQL 查询
Driver 和 Executor 日志 API	SPARK-MONITORING-CORE.md § Driver 和 Executor 日志 API	无需活动会话即可直接获取日志
Livy 日志 API	SPARK-MONITORING-CORE.md § Livy 日志 API	会话级日志，支持按字节偏移分页
资源使用情况 API	SPARK-MONITORING-CORE.md § 资源使用情况 API	vCore 时间线、空闲/运行中的核心数和效率指标
监控诊断工作流	SPARK-MONITORING-CORE.md § 使用监控 API 的诊断工作流	使用监控 API 逐步进行分诊

5. 诊断工作流（从这里开始进行活动分诊）

任务	参考	说明
自动诊断工作流（完整）	automated-diagnostic-workflow.md	步骤 1–7：解析 → 按状态路由 → 故障/性能/资源/健康状况 → 报告。包括步骤 1b 的过期数据回退方案和报告模板
诊断层级	diagnostic-workflow.md § 诊断层级	Tier 1（在线 REST）与 Tier 2（本地 SHS）
关键诊断模式	diagnostic-workflow.md § 关键诊断模式	症状 → 首要检查项 → 可能原因查询
严重程度阈值	diagnostic-workflow.md § 严重程度阈值	用于对发现进行分类的指标阈值
手动 CLI 操作示例	diagnostic-workflow.md § 手动 CLI 操作示例	供手动使用的临时诊断命令
Pipeline 运行诊断	pipeline-diagnosis.md	诊断一次 Pipeline 运行中的所有 Spark 活动（步骤 P1–P6）

6. 作业故障诊断

任务	参考	说明
故障分诊工作流	job-diagnostics.md § 故障分诊工作流	用于诊断故障的分步决策树
作业故障分类	job-diagnostics.md § 故障分类	OOM、shuffle、超时、依赖项和配置错误
通过 REST 读取 Spark 日志	job-diagnostics.md § 通过 REST 读取 Spark 日志	从 Livy 获取 Driver/Executor 日志
作业实例历史记录	job-diagnostics.md § 作业实例历史记录	查询近期运行记录、比较运行时长并检测回归

7. Livy 会话健康状况

任务	参考资料	说明
会话健康状况评估	session-health.md § Livy Session Lifecycle	会话状态、转换过程、预期时长
空闲和僵尸会话检测	session-health.md § Idle and Zombie Session Detection	查找并清理泄漏的会话
会话资源监控	session-health.md § Session Resource Monitoring	通过 Livy 监控内存和执行器使用情况
会话恢复模式	session-health.md § Session Recovery Patterns	重启策略和会话替换

8. 性能诊断

任务	参考资料	说明
性能反模式	performance-patterns.md § Anti-Patterns	溢写、混洗、数据倾斜、小文件、误用 collect
阶段和任务分析	performance-patterns.md § Stage and Task Analysis	通过 REST 读取 Spark UI 指标
优化方案	performance-patterns.md § Optimization Recipes	分区调优、广播联接、缓存
容量和资源诊断	performance-patterns.md § Capacity and Resource Diagnostics	CU 消耗、节流检测

9. 离线／深入分析工具

任务	参考资料	说明
JobInsight 事件日志副本	jobinsight-api.md § LogUtils.copyEventLog	将事件日志从 Fabric 复制到 OneLake，以供离线分析
本地 Spark History Server	spark-history-server.md § Overview	启动本地 SHS，以查看完整的 Spark UI（DAG、任务、SQL 计划）

---

必须／优先／避免

必须执行

• 尝试修复前，务必先获取作业／会话状态
• 使用 COMMON-CLI.md 中的工作区和项目发现功能——切勿硬编码 ID
• 提交诊断语句前，先检查 Livy 会话状态
• 按照故障分诊工作流进行系统化诊断
• 读取原始日志前，务必先检查 Spark Advisor API——它通常能立即找出根本原因
• 尝试基于 Livy 的诊断前，先使用监控 API（无需活动会话）
• 每隔 10–30 秒轮询作业／会话状态；诊断超时设为 30 分钟
• 诊断输出中务必包含 Notebook Snapshot URL——它的保留时间最长，并支持在 Fabric UI 中按单元格检查

优先选择

• 在判定为回归问题前，查询作业实例历史以建立基线

• 对诊断查询重复使用现有的空闲会话，而不是创建新会话

• 作业运行缓慢时，先检查容量利用率，再判断是否是 Spark 代码的问题

• 使用 az rest 和 JMESPath 过滤，从大型 API 响应中提取特定字段

• 通过 Spark Advisor API 检查数据倾斜、任务错误和超时，而不是手动解析日志

• 在建议扩容前，使用 Resource Usage API 的 coreEfficiency 指标量化集群利用率

• 对比作业实例历史（最近 5 次运行），在深入排查前检测回归问题

• 对于 MLV 刷新调度、监控或运行历史，请使用 mlv-operations-cli。对于底层 Spark 作业故障（OOM、数据倾斜、Shuffle 溢出）的诊断，请继续使用此技能——MLV 刷新会作为 Spark 作业执行，其日志可通过相同的监控 API 访问。

• MLV 故障分类——诊断 MLV 刷新失败时，先对错误分类，再深入排查：

  错误模式	类别	诊断路径
  MLV_SPARK_SESSION_REQUEST_SUBMISSION_FAILED	基础设施	容量已暂停或不可用，Spark 池配置错误。先检查容量状态。
  MLV_SELECTED_NOT_FOUND	配置	MLV 表已删除或重命名。通过 SHOW MATERIALIZED LAKE VIEWS IN schema 验证表是否存在。
  OutOfMemoryError / SparkOutOfMemory	资源	源数据增长，超出集群容量。通过 Spark Advisor 检查内存压力。
  ShuffleBlockFetchFailed / 数据倾斜	性能	数据分布不均。使用 Resource Usage API 找出倾斜分区。
  DeltaTableVersionNotFound	依赖项	源表已被清理，版本低于保留阈值。延长 delta.logRetentionDuration。
  ConstraintViolationException / ON MISMATCH	数据质量	DQ 约束导致行被丢弃或失败。在上游检查源数据质量。
  超时（运行时间 > 24 小时）	规模	血缘过大，无法在单次运行中完成。在不同的湖仓之间拆分为较小的血缘组。

避免

• 未检查会话是否有活动语句就终止会话
• 为每个诊断查询都创建新会话（重复使用空闲会话）
• 未检查 Livy 的实际内存指标就认定发生了 OOM
• 在诊断脚本中硬编码工作区或项目 ID
• 未先通过 Admin API 检查容量限制就诊断性能问题
• 向 busy 状态的会话提交诊断语句

---

示例

示例 1：诊断笔记本失败

用户提示：“为什么我的笔记本 ETL_Daily 在 Production 工作区中运行失败？”

Agent 工作流：

1. 解析工作区 → workspaceId，项目 → itemId（Notebook）
2. 列出最近的 Livy 会话，自动选择失败的会话
3. 查询 Spark Advisor → 发现执行器上出现 TaskError: OutOfMemoryError
4. 查询 /stages → 确认数据倾斜（阶段 5 中最大值与中位数之比为 12×）
5. 提交包含 HIGH 级发现和修复建议的报告

示例 2：排查卡住的 Livy 会话

用户提示：“我的 Livy 会话 abc-1234 卡在 starting 状态”

Agent 工作流：

1. 直接使用会话 ID，查询会话状态
2. 列出工作区中的所有会话 → 检测到 8 个并发会话（容量压力）
3. 检查 Livy 日志 → 没有错误，只是排队中
4. 报告：容量争用，建议等待或取消空闲会话

示例 3：查找管道失败的根本原因

用户提示：“诊断 Analytics 工作区中的管道运行 5678”

Agent 工作流：

1. 解析管道，调用 queryActivityRuns 查询运行 5678
2. 找到 2 个 Notebook 活动：一个成功，一个失败
3. 从失败活动中提取 output.result.error.{ename, evalue, traceback}
4. 构建 Notebook Snapshot URL，以便逐单元格检查
5. 提供错误详情、快照链接和建议的修复方法

---

快速开始

环境设置

应用 COMMON-CLI.md 中的环境检测，以设置：

• $FABRIC_API_BASE 和 $FABRIC_RESOURCE_SCOPE
• 用于 Livy 操作的 $FABRIC_API_URL 和 $LIVY_API_PATH

身份验证：使用 COMMON-CLI.md § Authentication Recipes 中的令牌获取方式。

---

自动诊断工作流

当用户提供简单的提示词（例如，“诊断我的笔记本 ETL_Pipeline”、“Spark 应用程序 abc-123 有什么问题？”、“检查工作区 Production 是否存在问题”）时，遵循以下快速路径摘要。完整流程、边缘情况（数据过期、仅管道会话）、报告模板和保留详情，请参阅 references/automated-diagnostic-workflow.md。

入口（用户提供的信息）

用户提供的信息	Agent 解析结果
工作区名称	→ workspaceId（通过工作区列表和名称筛选）
笔记本 / SJD / Lakehouse 名称	→ itemId（通过项目列表和名称/类型筛选）
管道名称 + 运行 ID	→ 子 Spark 活动 → 参见 pipeline-diagnosis.md
Livy 会话 ID 或 Spark 应用 ID	→ 直接使用
未提供具体信息	→ 询问工作区名称 + 项目名称

项目类型对应的 API 路径

项目类型	Livy 会话路径	作业实例路径
笔记本	/notebooks/{id}/livySessions	/items/{id}/jobs/instances
Spark 作业定义	/sparkJobDefinitions/{id}/livySessions	/items/{id}/jobs/instances
Lakehouse	/lakehouses/{id}/livySessions	/lakehouses/{id}/jobs/instances

所有会话 API 路径均遵循以下格式：$FABRIC_API_URL/workspaces/$workspaceId/<itemTypePath>/$itemId/livySessions/$livyId/applications/$appId/<endpoint> — 参见 SPARK-MONITORING-CORE.md。

步骤概览

步骤	时机	操作	自动标记规则
1. 解析并发现	始终	解析工作区 → 项目 → 列出最近的 Livy 会话；如果没有歧义则自动选择，否则提示用户	—
1b. 回退方案	会话返回 404 / Spark Monitoring 数据已过期	尝试 queryActivityRuns（管道）→ Job Instance failureReason → 构造 Notebook Snapshot URL	参见参考文档 § 步骤 1b
2. 按状态路由	步骤 1 之后	Failed → 3+4+5 · Succeeded/InProgress → 4+5 · Cancelled → 记录+3 · idle/busy/starting → 6 · dead/killed/error → 3+6	—
3. 故障分析	Failed / Cancelled / dead	按顺序查询：Spark Advisor → 驱动程序 stderr → Job Instance → 执行器日志 → Livy 日志 → 资源使用情况。根本原因明确后停止。	与 job-diagnostics.md § 快速参考表 中的规则匹配
4. 性能	始终（1b 路径除外）	/stages、/allexecutors	偏斜 max/median > 3× · 溢写 diskBytesSpilled > 0 · GC jvmGcTime/executorRunTime > 20% · shuffle > 1 GB · 任务 < 100ms
5. 资源利用率	始终（1b 路径除外）	/resourceUsage	coreEfficiency < 0.3 → 高 · idleTime/duration > 0.4 → 中
6. 会话健康状况	空闲/僵尸检查	GET /workspaces/$workspaceId/spark/livySessions	idle 且没有近期语句 → 僵尸 · starting 状态超出预期时间 → 容量问题
7. 编制报告	最后	按严重性排序的问题表 + Notebook Snapshot 链接 + 建议的修复方案	模板参见参考文档 § 步骤 7

关键原则：始终先检查 Spark Advisor——它会预先计算，并且无需解析日志即可识别大多数根本原因。管道运行通过 queryActivityRuns 提供最丰富的错误数据（ename、evalue、traceback、单元格/行号）——参见 pipeline-diagnosis.md。

数据保留警告：Spark Monitoring API 数据（日志、阶段、advisor）通常会在会话结束后的数分钟至数小时内过期。请及时诊断故障。如果 API 返回 404，请跳到参考文档中的步骤 1b。

二级升级处理：如果数据被截断、遇到 HTTP 408/504，或需要可视化 DAG/SQL 计划，建议使用离线 Spark History Server 工作流。