Back to Details

platform-apex-logs-debug

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

platform-apex-logs-debug: Salesforce Debug Log Analysis & Troubleshooting

platform-apex-logs-debug: 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限制诊断、堆栈跟踪解读、慢查询排查、堆/CPU压力分析，或基于日志证据的从复现到修复的闭环流程。

When This Skill Owns the Task

此技能负责的任务场景

Use 
platform-apex-logs-debug
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 → platform-apex-test-run
  • generating or implementing the code fix → platform-apex-generate
  • debugging Agentforce session traces / parquet telemetry → agentforce-observe
当工作涉及以下内容时，使用
platform-apex-logs-debug
：
  • Salesforce的.log文件
  • 堆栈跟踪与异常分析
  • governor限制
  • SOQL / DML / CPU / 堆内存故障排查
  • 从日志中提取查询计划或性能证据
当用户进行以下操作时，请转至其他技能：
  • 运行或修复Apex测试 → platform-apex-test-run
  • 生成或实施代码修复 → platform-apex-generate
  • 调试Agentforce会话追踪/parquet遥测数据 → agentforce-observe

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
询问或推断以下信息：
  • 组织别名
  • 失败的事务/用户流程/测试名称
  • 大致时间戳或事务窗口
  • 已知的用户/记录/请求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限制
  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
Issue: <摘要>
Location: <类 / 行 / 事务>
Root cause: <解释>
Severity: Critical | Warning | Info
Fix: <具体操作>
Verify: <测试或重新运行步骤>

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 
platform-apex-generate
This skill diagnoses; it does not rewrite Apex code
Delegate test execution to 
platform-apex-test-run
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帮助用户优先处理问题
将代码生成任务委托给
platform-apex-generate
此技能仅负责诊断，不重写Apex代码
将测试执行任务委托给
platform-apex-test-run
此技能不运行或修复测试类
未读取
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
陷阱解决方法
日志被截断至2MB降低调试级别（例如
ApexCode: INFO
、
ApexProfiling: FINE
）并重新捕获
同一问题同时表现为SOQL和CPU问题优先修复循环中执行SOQL的问题 — 它通常是导致CPU峰值的次要原因
设置跟踪标志后无日志显示验证跟踪标志的
ExpirationDate
是否在未来，且追踪的是正确用户
异步上下文改变限制值异步CPU限制为60,000毫秒，同步为10,000毫秒 — 标记限制前先检查事务类型
堆栈跟踪指向框架代码行，而非用户代码沿着调用栈向上追溯，跳过触发器处理程序，找到原始用户代码

Cross-Skill Integration

跨技能集成

NeedDelegate toReason
Implement Apex fixplatform-apex-generatecode change generation / review
Reproduce via testsplatform-apex-test-runtest execution and coverage loop
Deploy fixplatform-metadata-deploydeployment orchestration
Create debugging dataplatform-data-managetargeted seed / repro data
需求委托至原因
实施Apex修复platform-apex-generate代码变更生成/评审
通过测试复现platform-apex-test-run测试执行与覆盖闭环
部署修复platform-metadata-deploy部署编排
创建调试数据platform-data-manage目标种子/复现数据

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限制参考值
references/log-analysis-tools.md
工具指南：Apex Log Analyzer、开发者控制台、CLI grep模式
references/benchmarking-guide.md
性能基准测试技术、基准数据和反模式
references/scoring-rubric.md
用于评估分析质量的100分评分标准
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分析不完整