debugging-apex-logs

debugging-apex-logs：Salesforce 调试日志分析与故障排查

当用户需要根据调试日志进行根因分析时使用此技能：诊断 governor limit、解读堆栈跟踪、调查慢查询、分析堆内存 / CPU 压力，或根据日志证据进行复现到修复的闭环。

此技能负责的任务

当工作涉及以下内容时，使用 debugging-apex-logs：

• Salesforce 的 .log 文件
• 堆栈跟踪和异常分析
• governor limit
• SOQL / DML / CPU / 堆内存故障排查
• 从日志中提取的查询计划或性能证据

以下情况应委派给其他技能：

• 运行或修复 Apex 测试 → running-apex-tests
• 生成或实现代码修复 → generating-apex
• 调试 Agentforce 会话跟踪 / parquet 遥测数据 → observing-agentforce

---

首先收集所需上下文

询问或推断：

• org 别名
• 失败的事务 / 用户流程 / 测试名称
• 大致时间戳或事务时间范围
• 已知的用户 / 记录 / 请求 ID
• 目标是仅诊断，还是诊断并进行修复闭环

---

建议的工作流

1. 获取日志

使用 references/cli-commands.md 中的命令，为目标 org 列出、下载或流式传输日志。

2. 按以下顺序分析

1. 入口点和事务类型
2. 异常 / 致命错误
3. governor limit
4. 重复的 SOQL / DML 模式
5. CPU / 堆内存热点
6. callout 耗时和外部故障

3. 对严重程度进行分类

• Critical — 运行时故障、硬性限制、数据损坏风险
• Warning — 接近限制、非选择性查询、慢速路径
• Info — 优化机会或代码整洁性问题

4. 建议最小且正确的修复

优先选择以下修复方案：

• 针对根因
• 可安全批量处理
• 可测试
• 易于通过重新运行验证

扩展工作流：references/analysis-playbook.md

---

高价值问题模式

问题	主要信号	默认修复方向
循环中的 SOQL	重复调用路径中反复出现 SOQL_EXECUTE_BEGIN	只查询一次，使用映射 / 分组集合
循环中的 DML	反复出现 DML_BEGIN 模式	收集行，然后一次性执行批量 DML
非选择性查询	扫描行数过多 / 选择性差	添加索引筛选条件，缩小范围
CPU 压力	CPU 使用量接近同步限制	降低算法复杂度、缓存，在适用时改为异步处理
堆内存压力	堆内存使用量接近同步限制	使用 SOQL for 循环流式处理，减少内存中的数据
空指针 / 致命错误	EXCEPTION_THROWN / FATAL_ERROR	防范空值假设，修复空查询处理

扩展示例：references/common-issues.md

---

输出格式

完成分析时，按以下顺序报告：

1. 发生了什么故障
2. 故障发生的位置（类 / 方法 / 行 / 事务阶段）
3. 故障原因（根因，而不仅是症状）
4. 严重程度
5. 建议的修复方案
6. 验证步骤

建议格式：

Issue: <summary>
Location: <class / line / transaction>
Root cause: <explanation>
Severity: Critical | Warning | Info
Fix: <specific action>
Verify: <test or rerun step>

---

规则 / 约束

规则	原因
修复建议始终以日志证据为依据	避免推测性诊断 — 根因必须能在日志中追溯
对每个发现的问题报告全部六个输出字段	确保每个问题的发现都完整且可执行
将每项发现分类为 Critical、Warning 或 Info	帮助用户确定应优先处理哪些问题
将代码生成委派给 generating-apex	此技能负责诊断，不负责重写 Apex 代码
将测试执行委派给 running-apex-tests	此技能不运行或修复测试类
未读取 LIMIT_USAGE 事件前，绝不假设限制尚有余量	失败点中不可见的先前操作可能已消耗限制

---

注意事项

陷阱	解决方案
日志在 2 MB 处被截断	降低调试级别（例如，ApexCode: INFO、ApexProfiling: FINE），然后重新捕获
同一个问题既表现为 SOQL 问题，也表现为 CPU 问题	优先修复循环中的 SOQL——它通常会进一步导致 CPU 飙升
设置跟踪标记后没有出现日志	确认跟踪标记的 ExpirationDate 是未来时间，并且跟踪的是正确的用户
异步上下文会改变限制值	异步 CPU 限制为 60,000 ms，同步为 10,000 ms——报告限制问题前，请先检查事务类型
堆栈跟踪指向框架代码行，而非用户代码	沿调用堆栈向上检查，越过触发器处理程序，找到起始用户代码

---

跨技能集成

需求	委派给	原因
实现 Apex 修复	generating-apex	生成 / 审查代码变更
通过测试复现	running-apex-tests	测试执行与覆盖率循环
部署修复	deploying-metadata	部署编排
创建调试数据	handling-sf-data	有针对性地创建种子数据 / 复现数据

---

参考文件索引

文件	何时阅读
references/analysis-playbook.md	从这里开始——适用于任何调试会话的扩展分步工作流
references/common-issues.md	快速查找循环中的 SOQL、循环中的 DML、CPU / 堆压力以及空指针模式
references/cli-commands.md	用于检索、流式传输和管理调试日志的 SF CLI 命令
references/debug-log-reference.md	完整的事件类型目录、日志级别和治理限制参考值
references/log-analysis-tools.md	工具指南：Apex Log Analyzer、Developer Console、CLI grep 模式
references/benchmarking-guide.md	性能基准测试技术、基准数据和反模式
references/scoring-rubric.md	用于评估分析质量的 100 分评分标准
assets/benchmarking-template.cls	可复制粘贴的 Anonymous Apex 模板，用于运行性能基准测试
assets/cpu-heap-optimization.cls	用于减少 CPU 时间和堆分配的 Apex 模式
assets/dml-in-loop-fix.cls	用于解决循环中的 DML 违规的修复前后示例
assets/soql-in-loop-fix.cls	用于解决循环中的 SOQL 违规的修复前后示例
assets/null-pointer-fix.cls	用于防范空指针异常的模式

---

评分指南

分数	含义
90+	专业级分析，修复建议完善
80–89	分析良好，仅有少量遗漏
70–79	可以接受，但可能遗漏次要问题
60–69	仅提供部分诊断
< 60	分析不完整