Back to Details

debugging-apex-logs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

debugging-apex-logs: Salesforce Debug Log Analysis & Troubleshooting

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

Use this skill when the user needs root-cause analysis from debug logs: governor-limit diagnosis, stack-trace interpretation, slow-query investigation, heap / CPU pressure analysis, or a reproduction-to-fix loop based on log evidence.
当用户需要通过调试日志进行根因分析时使用本技能：包括Governor Limits诊断、堆栈跟踪解读、慢查询调查、堆/CPU压力分析，或基于日志证据的“复现-修复”循环。

When This Skill Owns the Task

本技能负责的任务场景

Use 
debugging-apex-logs
when the work involves:
  • .log
    files from Salesforce
  • stack traces and exception analysis
  • governor limits
  • SOQL / DML / CPU / heap troubleshooting
  • query-plan or performance evidence extracted from logs
Delegate elsewhere when the user is:
  • running or repairing Apex tests → running-apex-tests
  • generating or implementing the code fix → generating-apex
  • debugging Agentforce session traces / parquet telemetry → observing-agentforce
当工作涉及以下内容时，使用
debugging-apex-logs
：
  • Salesforce的.log文件
  • 堆栈跟踪与异常分析
  • Governor Limits
  • SOQL / DML / CPU / 堆内存故障排查
  • 从日志中提取查询计划或性能证据
当用户进行以下操作时，请转至其他技能：
  • 运行或修复Apex测试 → running-apex-tests
  • 生成或实现代码修复 → generating-apex
  • 调试Agentforce会话跟踪/Parquet遥测数据 → observing-agentforce

Required Context to Gather First

需先收集的必要上下文信息

Ask for or infer:
  • org alias
  • failing transaction / user flow / test name
  • approximate timestamp or transaction window
  • user / record / request ID if known
  • whether the goal is diagnosis only or diagnosis + fix loop
询问或推断：
  • 组织别名（org alias）
  • 失败的事务/用户流程/测试名称
  • 大致时间戳或事务窗口
  • 已知的用户/记录/请求ID
  • 目标仅为诊断还是“诊断+修复”循环

Recommended Workflow

推荐工作流程

1. Retrieve logs

1. 获取日志

Use the commands in references/cli-commands.md to list, download, or stream logs for the target org.
使用references/cli-commands.md中的命令，列出、下载或流式传输目标组织的日志。

2. Analyze in this order

2. 按以下顺序分析

  1. entry point and transaction type
  2. exceptions / fatal errors
  3. governor limits
  4. repeated SOQL / DML patterns
  5. CPU / heap hotspots
  6. callout timing and external failures
  1. 入口点与事务类型
  2. 异常/致命错误
  3. Governor Limits
  4. 重复的SOQL / DML模式
  5. CPU / 堆内存热点
  6. 调用超时与外部故障

3. Classify severity

3. 分类严重程度

  • Critical — runtime failure, hard limit, corruption risk
  • Warning — near-limit, non-selective query, slow path
  • Info — optimization opportunity or hygiene issue
  • Critical（严重） — 运行时失败、硬限制触发、存在数据损坏风险
  • Warning（警告） — 接近限制、非选择性查询、慢执行路径
  • Info（信息） — 优化机会或代码规范问题

4. Recommend the smallest correct fix

4. 推荐最小化的正确修复方案

Prefer fixes that are:
  • root-cause oriented
  • bulk-safe
  • testable
  • easy to verify with a rerun
Expanded workflow: references/analysis-playbook.md
优先选择以下类型的修复：
  • 针对根因的
  • 支持批量处理的
  • 可测试的
  • 易于通过重新运行验证的
扩展工作流程：references/analysis-playbook.md

High-Signal Issue Patterns

高信号问题模式

IssuePrimary signalDefault fix direction
SOQL in looprepeating 
SOQL_EXECUTE_BEGIN
in a repeated call path		query once, use maps / grouped collections
DML in looprepeated 
DML_BEGIN
patterns		collect rows, bulk DML once
Non-selective queryhigh rows scanned / poor selectivityadd indexed filters, reduce scope
CPU pressureCPU usage approaching sync limitreduce algorithmic complexity, cache, async where valid
Heap pressureheap usage approaching sync limitstream with SOQL for-loops, reduce in-memory data
Null pointer / fatal error
EXCEPTION_THROWN
/ 
FATAL_ERROR
guard null assumptions, fix empty-query handling
Expanded examples: references/common-issues.md
问题主要信号默认修复方向
SOQL循环调用重复调用路径中出现重复的
SOQL_EXECUTE_BEGIN
一次性查询，使用映射/分组集合
DML循环调用出现重复的
DML_BEGIN
模式		收集行数据，批量执行DML
非选择性查询扫描行数多/选择性差添加索引过滤条件，缩小查询范围
CPU压力CPU使用率接近同步模式限制降低算法复杂度，使用缓存，合理使用异步处理
堆内存压力堆内存使用率接近同步模式限制使用SOQL循环流式处理，减少内存中存储的数据
空指针/致命错误出现
EXCEPTION_THROWN
/ 
FATAL_ERROR
增加空值判断，修复空查询的处理逻辑
扩展示例：references/common-issues.md

Output Format

输出格式

When finishing analysis, report in this order:
  1. What failed
  2. Where it failed (class / method / line / transaction stage)
  3. Why it failed (root cause, not just symptom)
  4. How severe it is
  5. Recommended fix
  6. Verification step
Suggested shape:
text
Issue: <summary>
Location: <class / line / transaction>
Root cause: <explanation>
Severity: Critical | Warning | Info
Fix: <specific action>
Verify: <test or rerun step>
完成分析后，按以下顺序报告：
  1. 故障内容
  2. 故障位置（类/方法/行/事务阶段）
  3. 故障原因（根因，而非仅症状）
  4. 严重程度
  5. 推荐修复方案
  6. 验证步骤
建议格式：
text
问题: <摘要>
位置: <类 / 行 / 事务>
根因: <说明>
严重程度: Critical | Warning | Info
修复方案: <具体操作>
验证: <测试或重新运行步骤>

Rules / Constraints

规则/约束

RuleRationale
Always base fix recommendations on log evidenceAvoid speculative diagnosis — root cause must be traceable in the log
Report all six output fields for every issue foundEnsures actionable, complete findings for each problem
Classify every finding as Critical, Warning, or InfoHelps the user prioritize which issues to address first
Delegate code generation to 
generating-apex
This skill diagnoses; it does not rewrite Apex code
Delegate test execution to 
running-apex-tests
This skill does not run or repair test classes
Never assume limits are safe without reading 
LIMIT_USAGE
events		Limits may be consumed by earlier operations not visible in the failure point
规则理由
修复建议必须始终基于日志证据避免推测性诊断 — 根因必须可在日志中追溯
每个发现的问题都需报告全部六个输出字段确保每个问题的结果可执行且完整
每个发现都需归类为Critical、Warning或Info帮助用户优先处理问题
代码生成任务转至
generating-apex
本技能仅负责诊断，不重写Apex代码
测试执行任务转至
running-apex-tests
本技能不运行或修复测试类
未读取
LIMIT_USAGE
事件前，切勿假设限制是安全的		限制可能被故障点之前的操作消耗，而这些操作在故障点不可见

Gotchas

常见陷阱

PitfallResolution
Log truncated at 2 MBReduce debug levels (e.g., 
ApexCode: INFO
, 
ApexProfiling: FINE
) and re-capture
Same issue appears as both SOQL and CPU problemFix SOQL-in-loop first — it typically drives the CPU spike as a secondary effect
No logs appear after trace flag is setVerify the trace flag 
ExpirationDate
is in the future and the correct user is traced
Async context changes limit valuesCPU limit is 60,000 ms async vs 10,000 ms sync — check transaction type before flagging limits
Stack trace points to framework line, not user codeWalk up the call stack past trigger handlers to find the originating user code
陷阱解决方法
日志被截断至2 MB降低调试级别（例如
ApexCode: INFO
、
ApexProfiling: FINE
）并重新捕获日志
同一问题同时表现为SOQL和CPU问题优先修复SOQL循环调用 — 这通常是CPU飙升的次要原因
设置跟踪标志后无日志生成验证跟踪标志的
ExpirationDate
是否在未来，且跟踪的是正确用户
异步上下文会改变限制值CPU限制在异步模式下为60,000毫秒，同步模式下为10,000毫秒 — 标记限制问题前需检查事务类型
堆栈跟踪指向框架代码行，而非用户代码沿着调用栈向上追溯，跳过触发器处理程序，找到原始用户代码

Cross-Skill Integration

跨技能集成

NeedDelegate toReason
Implement Apex fixgenerating-apexcode change generation / review
Reproduce via testsrunning-apex-teststest execution and coverage loop
Deploy fixdeploying-metadatadeployment orchestration
Create debugging datahandling-sf-datatargeted seed / repro data
需求转至技能原因
实现Apex修复generating-apex代码变更生成/审核
通过测试复现问题running-apex-tests测试执行与覆盖循环
部署修复方案deploying-metadata部署编排
创建调试数据handling-sf-data针对性的种子/复现数据

Reference File Index

参考文件索引

FileWhen to read
references/analysis-playbook.md
Start here — expanded step-by-step workflow for any debugging session
references/common-issues.md
Quick lookup for SOQL in loop, DML in loop, CPU/heap pressure, null pointer patterns
references/cli-commands.md
SF CLI commands for retrieving, streaming, and managing debug logs
references/debug-log-reference.md
Full event type catalog, log levels, and governor limit reference values
references/log-analysis-tools.md
Tool guide: Apex Log Analyzer, Developer Console, CLI grep patterns
references/benchmarking-guide.md
Performance benchmarking techniques, benchmark data, and anti-patterns
references/scoring-rubric.md
100-point scoring rubric for evaluating analysis quality
assets/benchmarking-template.cls
Copy-paste Anonymous Apex template for running performance benchmarks
assets/cpu-heap-optimization.cls
Apex patterns for reducing CPU time and heap allocation
assets/dml-in-loop-fix.cls
Before/after example for resolving DML-in-loop violations
assets/soql-in-loop-fix.cls
Before/after example for resolving SOQL-in-loop violations
assets/null-pointer-fix.cls
Patterns for guarding against null pointer exceptions
文件阅读场景
references/analysis-playbook.md
入门必读 — 适用于任何调试会话的扩展分步工作流程
references/common-issues.md
快速查找SOQL循环调用、DML循环调用、CPU/堆内存压力、空指针等模式
references/cli-commands.md
用于检索、流式传输和管理调试日志的SF CLI命令
references/debug-log-reference.md
完整的事件类型目录、日志级别和Governor Limits参考值
references/log-analysis-tools.md
工具指南：Apex Log Analyzer、开发者控制台、CLI grep模式
references/benchmarking-guide.md
性能基准测试技术、基准数据和反模式
references/scoring-rubric.md
用于评估分析质量的百分制评分标准
assets/benchmarking-template.cls
可复制粘贴的匿名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
防范空指针异常的模式

Score Guide

评分指南

ScoreMeaning
90+Expert analysis with strong fix guidance
80–89Good analysis with minor gaps
70–79Acceptable but may miss secondary issues
60–69Partial diagnosis only
< 60Incomplete analysis
分数含义
90+专家级分析，修复指导清晰有力
80–89良好分析，存在微小漏洞
70–79合格，但可能遗漏次要问题
60–69仅完成部分诊断
< 60分析不完整