debugging-apex-logs
forcedotcom/sf-skills
Analyze Salesforce debug logs to diagnose governor limits, stack traces, and performance bottlenecks.
What is debugging-apex-logs?
This skill performs root-cause analysis on Salesforce debug logs to identify governor-limit violations, stack-trace exceptions, SOQL/DML patterns, and performance issues. Use it when analyzing .log files, troubleshooting slow queries, or investigating heap and CPU pressure in Apex execution.
- Retrieve and stream debug logs from Salesforce orgs using SF CLI
- Analyze stack traces and exception patterns to identify failure points
- Diagnose governor-limit consumption (SOQL, DML, CPU, heap)
- Detect SOQL-in-loop and DML-in-loop anti-patterns
- Evaluate query selectivity and performance hotspots
- Classify issues by severity (Critical, Warning, Info) with fix recommendations
How to install debugging-apex-logs
npx skills add https://github.com/forcedotcom/sf-skills --skill debugging-apex-logsHow to use debugging-apex-logs
- 1.Gather required context: org alias, failing transaction name, approximate timestamp, and user/record ID if known.
- 2.Use SF CLI commands (see references/cli-commands.md) to retrieve or stream .log files for the target org and transaction window.
- 3.Open the log and analyze in order: entry point, exceptions, governor limits, SOQL/DML patterns, CPU/heap hotspots, and callout timing.
- 4.For each issue found, report: What failed, Where it failed, Why it failed (root cause), Severity level, Recommended fix, and Verification step.
- 5.Delegate code implementation to generating-apex skill and test execution to running-apex-tests skill.
Use cases
- A trigger is hitting the DML governor limit; analyze the log to find repeated DML calls and recommend bulk collection patterns.
- A batch job times out; examine CPU and heap usage in the debug log to identify algorithmic complexity or memory leaks.
- A user reports slow page load; retrieve the debug log and trace SOQL execution patterns to find non-selective queries.
- An Apex test fails with a null pointer exception; parse the stack trace to locate the originating user code and guard conditions.
- A scheduled job consumes 95% of heap; stream the log to identify in-memory data structures and recommend SOQL for-loop streaming.
- Salesforce developers troubleshooting Apex runtime failures
- QA engineers reproducing and diagnosing production issues
- DevOps engineers analyzing batch job and async execution logs
- Technical leads reviewing performance bottlenecks before code review
debugging-apex-logs FAQ
Use debugging-apex-logs for analyzing existing .log files and diagnosing failures. Use running-apex-tests when you need to execute or repair test classes. This skill does not run tests; it analyzes logs from test or production execution.
Use SF CLI commands listed in references/cli-commands.md. Common commands: `sf apex log list` to view available logs, `sf apex log get --log-id <ID>` to download a specific log, or `sf apex log stream` to tail logs in real time.
Reduce debug levels (e.g., set ApexCode to INFO and ApexProfiling to FINE instead of FINEST) and re-capture the transaction. Truncation indicates too much detail is being logged; lower verbosity will capture the full transaction.
Fix SOQL-in-loop first. Repeated SOQL execution typically drives secondary CPU spikes. Check the log for repeating `SOQL_EXECUTE_BEGIN` events in a loop; if found, that is the primary issue.
This skill diagnoses and recommends fixes based on log evidence. Delegate code generation and refactoring to the generating-apex skill, and delegate test execution to running-apex-tests skill.
Full instructions (SKILL.md)
Source of truth, from forcedotcom/sf-skills.
name: debugging-apex-logs description: "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 running-apex-tests), generating or fixing Apex code (use generating-apex), or Agentforce session tracing (use observing-agentforce)." metadata: version: "1.1"
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:
.logfiles 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 |
Related skills
More from forcedotcom/sf-skills and the wider catalog.
deploying-metadata
Salesforce DevOps automation: deploy metadata safely with sf CLI v2, validate first, orchestrate CI/CD.
deploying-omnistudio-datapacks
Automate Vlocity DataPack deployment, validation, and retry workflows for OmniStudio/Industries configurations.
deploying-ui-bundle
Deploy UI bundle apps to Salesforce orgs with full metadata, permissions, and schema setup.
developing-agentforce
Build, modify, debug, and deploy Salesforce Agentforce agents using Agent Script.
developing-datacloud-code-extension
Develop and deploy custom Python transformations to Salesforce Data Cloud with init, scan, run, and deploy operations.
fetching-salesforce-docs
Retrieve and ground answers in official Salesforce documentation from developer.salesforce.com, help.salesforce.com, and other Salesforce-owned sources.