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

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.

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

---

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

---

Recommended Workflow

1. Retrieve logs

Use the commands in references/cli-commands.md to list, download, or stream logs for the target org.

2. Analyze in this order

entry point and transaction type
exceptions / fatal errors
governor limits
repeated SOQL / DML patterns
CPU / heap hotspots
callout timing and external failures

3. Classify severity

Critical — runtime failure, hard limit, corruption risk
Warning — near-limit, non-selective query, slow path
Info — optimization opportunity or hygiene issue

4. Recommend the smallest correct fix

Prefer fixes that are:

root-cause oriented
bulk-safe
testable
easy to verify with a rerun

Expanded workflow: references/analysis-playbook.md

---

High-Signal Issue Patterns

Issue	Primary signal	Default fix direction
SOQL in loop	repeating `SOQL_EXECUTE_BEGIN` in a repeated call path	query once, use maps / grouped collections
DML in loop	repeated `DML_BEGIN` patterns	collect rows, bulk DML once
Non-selective query	high rows scanned / poor selectivity	add indexed filters, reduce scope
CPU pressure	CPU usage approaching sync limit	reduce algorithmic complexity, cache, async where valid
Heap pressure	heap usage approaching sync limit	stream 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

---

Output Format

When finishing analysis, report in this order:

What failed
Where it failed (class / method / line / transaction stage)
Why it failed (root cause, not just symptom)
How severe it is
Recommended fix
Verification step

Suggested shape:

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

---

Rules / Constraints

Rule	Rationale
Always base fix recommendations on log evidence	Avoid speculative diagnosis — root cause must be traceable in the log
Report all six output fields for every issue found	Ensures actionable, complete findings for each problem
Classify every finding as Critical, Warning, or Info	Helps 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

---

Gotchas

Pitfall	Resolution
Log truncated at 2 MB	Reduce debug levels (e.g., `ApexCode: INFO`, `ApexProfiling: FINE`) and re-capture
Same issue appears as both SOQL and CPU problem	Fix SOQL-in-loop first — it typically drives the CPU spike as a secondary effect
No logs appear after trace flag is set	Verify the trace flag `ExpirationDate` is in the future and the correct user is traced
Async context changes limit values	CPU 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 code	Walk up the call stack past trigger handlers to find the originating user code

---

Cross-Skill Integration

Need	Delegate to	Reason
Implement Apex fix	generating-apex	code change generation / review
Reproduce via tests	running-apex-tests	test execution and coverage loop
Deploy fix	deploying-metadata	deployment orchestration
Create debugging data	handling-sf-data	targeted seed / repro data

---

Reference File Index

File	When 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

---

Score Guide

Score	Meaning
90+	Expert analysis with strong fix guidance
80–89	Good analysis with minor gaps
70–79	Acceptable but may miss secondary issues
60–69	Partial diagnosis only
< 60	Incomplete analysis

debugging-apex-logs