platform-apex-logs-debug: 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 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:
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 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 |
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
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 |
1---
2name: platform-apex-logs-debug
3description: "Salesforce debug log analysis and troubleshooting with 100-point scoring. TRIGGER when: user analyzes debug logs, hits governor limits, reads stack traces, or touches .log files from Salesforce orgs. DO NOT TRIGGER when: running Apex tests (use platform-apex-test-run), generating or fixing Apex code (use platform-apex-generate), or Agentforce session tracing (use agentforce-observe)."
4metadata:
5 version: "1.1"
6 domains: ["Platform"]
7 relatedSkills:
8 - "agentforce-observe"
9 - "platform-apex-generate"
10 - "platform-apex-test-run"
11 - "platform-data-manage"
12 - "platform-metadata-deploy"
13 - "platform-soql-query"
14 cliTools:
15 - tool: ["sf"]
16 semver: ">=2.0.0"
17 - tool: ["jq"]
18 semver: ">=1.6.0"
19---
20
21# platform-apex-logs-debug: Salesforce Debug Log Analysis & Troubleshooting
22
23Use 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.
24
25## When This Skill Owns the Task
26
27Use `platform-apex-logs-debug` when the work involves:
28- `.log` files from Salesforce
29- stack traces and exception analysis
30- governor limits
31- SOQL / DML / CPU / heap troubleshooting
32- query-plan or performance evidence extracted from logs
33
34Delegate elsewhere when the user is:
35- running or repairing Apex tests → [platform-apex-test-run](../platform-apex-test-run/SKILL.md)
36- generating or implementing the code fix → [platform-apex-generate](../platform-apex-generate/SKILL.md)
37- debugging Agentforce session traces / parquet telemetry → [agentforce-observe](../agentforce-observe/SKILL.md)
38
39---
40
41## Required Context to Gather First
42
43Ask for or infer:
44- org alias
45- failing transaction / user flow / test name
46- approximate timestamp or transaction window
47- user / record / request ID if known
48- whether the goal is diagnosis only or diagnosis + fix loop
49
50---
51
52## Recommended Workflow
53
54### 1. Retrieve logs
55
56Use the commands in [references/cli-commands.md](references/cli-commands.md) to list, download, or stream logs for the target org.
57
58### 2. Analyze in this order
591. entry point and transaction type
602. exceptions / fatal errors
613. governor limits
624. repeated SOQL / DML patterns
635. CPU / heap hotspots
646. callout timing and external failures
65
66### 3. Classify severity
67- **Critical** — runtime failure, hard limit, corruption risk
68- **Warning** — near-limit, non-selective query, slow path
69- **Info** — optimization opportunity or hygiene issue
70
71### 4. Recommend the smallest correct fix
72Prefer fixes that are:
73- root-cause oriented
74- bulk-safe
75- testable
76- easy to verify with a rerun
77
78Expanded workflow: [references/analysis-playbook.md](references/analysis-playbook.md)
79
80---
81
82## High-Signal Issue Patterns
83
84| Issue | Primary signal | Default fix direction |
85|---|---|---|
86| SOQL in loop | repeating `SOQL_EXECUTE_BEGIN` in a repeated call path | query once, use maps / grouped collections |
87| DML in loop | repeated `DML_BEGIN` patterns | collect rows, bulk DML once |
88| Non-selective query | high rows scanned / poor selectivity | add indexed filters, reduce scope |
89| CPU pressure | CPU usage approaching sync limit | reduce algorithmic complexity, cache, async where valid |
90| Heap pressure | heap usage approaching sync limit | stream with SOQL for-loops, reduce in-memory data |
91| Null pointer / fatal error | `EXCEPTION_THROWN` / `FATAL_ERROR` | guard null assumptions, fix empty-query handling |
92
93Expanded examples: [references/common-issues.md](references/common-issues.md)
94
95---
96
97## Output Format
98
99When finishing analysis, report in this order:
100
1011. **What failed**
1022. **Where it failed** (class / method / line / transaction stage)
1033. **Why it failed** (root cause, not just symptom)
1044. **How severe it is**
1055. **Recommended fix**
1066. **Verification step**
107
108Suggested shape:
109
110```text
111Issue: <summary>
112Location: <class / line / transaction>
113Root cause: <explanation>
114Severity: Critical | Warning | Info
115Fix: <specific action>
116Verify: <test or rerun step>
117```
118
119---
120
121## Rules / Constraints
122
123| Rule | Rationale |
124|------|-----------|
125| Always base fix recommendations on log evidence | Avoid speculative diagnosis — root cause must be traceable in the log |
126| Report all six output fields for every issue found | Ensures actionable, complete findings for each problem |
127| Classify every finding as Critical, Warning, or Info | Helps the user prioritize which issues to address first |
128| Delegate code generation to `platform-apex-generate` | This skill diagnoses; it does not rewrite Apex code |
129| Delegate test execution to `platform-apex-test-run` | This skill does not run or repair test classes |
130| Never assume limits are safe without reading `LIMIT_USAGE` events | Limits may be consumed by earlier operations not visible in the failure point |
131
132---
133
134## Gotchas
135
136| Pitfall | Resolution |
137|---------|------------|
138| Log truncated at 2 MB | Reduce debug levels (e.g., `ApexCode: INFO`, `ApexProfiling: FINE`) and re-capture |
139| Same issue appears as both SOQL and CPU problem | Fix SOQL-in-loop first — it typically drives the CPU spike as a secondary effect |
140| No logs appear after trace flag is set | Verify the trace flag `ExpirationDate` is in the future and the correct user is traced |
141| Async context changes limit values | CPU limit is 60,000 ms async vs 10,000 ms sync — check transaction type before flagging limits |
142| Stack trace points to framework line, not user code | Walk up the call stack past trigger handlers to find the originating user code |
143
144---
145
146## Cross-Skill Integration
147
148| Need | Delegate to | Reason |
149|---|---|---|
150| Implement Apex fix | [platform-apex-generate](../platform-apex-generate/SKILL.md) | code change generation / review |
151| Reproduce via tests | [platform-apex-test-run](../platform-apex-test-run/SKILL.md) | test execution and coverage loop |
152| Deploy fix | [platform-metadata-deploy](../platform-metadata-deploy/SKILL.md) | deployment orchestration |
153| Create debugging data | [platform-data-manage](../platform-data-manage/SKILL.md) | targeted seed / repro data |
154
155---
156
157## Reference File Index
158
159| File | When to read |
160|------|-------------|
161| `references/analysis-playbook.md` | Start here — expanded step-by-step workflow for any debugging session |
162| `references/common-issues.md` | Quick lookup for SOQL in loop, DML in loop, CPU/heap pressure, null pointer patterns |
163| `references/cli-commands.md` | SF CLI commands for retrieving, streaming, and managing debug logs |
164| `references/debug-log-reference.md` | Full event type catalog, log levels, and governor limit reference values |
165| `references/log-analysis-tools.md` | Tool guide: Apex Log Analyzer, Developer Console, CLI grep patterns |
166| `references/benchmarking-guide.md` | Performance benchmarking techniques, benchmark data, and anti-patterns |
167| `references/scoring-rubric.md` | 100-point scoring rubric for evaluating analysis quality |
168| `assets/benchmarking-template.cls` | Copy-paste Anonymous Apex template for running performance benchmarks |
169| `assets/cpu-heap-optimization.cls` | Apex patterns for reducing CPU time and heap allocation |
170| `assets/dml-in-loop-fix.cls` | Before/after example for resolving DML-in-loop violations |
171| `assets/soql-in-loop-fix.cls` | Before/after example for resolving SOQL-in-loop violations |
172| `assets/null-pointer-fix.cls` | Patterns for guarding against null pointer exceptions |
173
174---
175
176## Score Guide
177
178| Score | Meaning |
179|---|---|
180| 90+ | Expert analysis with strong fix guidance |
181| 80–89 | Good analysis with minor gaps |
182| 70–79 | Acceptable but may miss secondary issues |
183| 60–69 | Partial diagnosis only |
184| < 60 | Incomplete analysis |
forcedotcom