platform-apex-logs-debug
forcedotcom/sf-skills
Analyze Salesforce debug logs to diagnose governor limits, stack traces, and performance bottlenecks.
What is platform-apex-logs-debug?
This skill performs root-cause analysis on Salesforce debug logs to identify and troubleshoot issues like governor-limit violations, stack-trace exceptions, SOQL/DML in loops, and CPU/heap pressure. Use it when analyzing .log files from Salesforce orgs to diagnose failures and guide fixes—but delegate code generation to platform-apex-generate and test execution to platform-apex-test-run.
- Retrieve and stream debug logs from Salesforce orgs using SF CLI
- Analyze stack traces, exceptions, and fatal errors to identify root causes
- Diagnose governor-limit violations (SOQL, DML, CPU, heap) with evidence from log events
- Detect performance anti-patterns: SOQL-in-loop, DML-in-loop, non-selective queries, CPU/heap hotspots
- Classify findings by severity (Critical, Warning, Info) and recommend targeted fixes with verification steps
How to install platform-apex-logs-debug
npx skills add https://github.com/forcedotcom/sf-skills --skill platform-apex-logs-debug- Salesforce org with debug-log access (requires appropriate user permissions)
- SF CLI version 2.0.0 or later installed
- jq version 1.6.0 or later for log parsing and filtering (optional but recommended)
How to use platform-apex-logs-debug
- 1.Gather context: org alias, failing transaction name or user flow, approximate timestamp, and whether the goal is diagnosis only or diagnosis + fix loop.
- 2.Retrieve logs using SF CLI commands (e.g., `sf apex log list`, `sf apex log get`) or stream logs for the target org and user.
- 3.Analyze logs in order: entry point and transaction type, exceptions/fatal errors, governor limits, repeated SOQL/DML patterns, CPU/heap hotspots, and callout timing.
- 4.Classify each issue as Critical (runtime failure, hard limit), Warning (near-limit, non-selective query), or Info (optimization opportunity).
- 5.Report findings in six fields: What failed, Where it failed, Why it failed (root cause), Severity, Recommended fix, and Verification step.
Use cases
- A trigger is hitting governor limits; retrieve logs and identify whether SOQL, DML, or CPU is the bottleneck, then recommend the smallest fix.
- A user reports a slow transaction; analyze the debug log to find repeated SOQL queries or inefficient heap usage and suggest optimization.
- An exception occurs in production; pull the debug log, trace the call stack, and pinpoint the null-pointer or logic error causing the failure.
- A batch job fails partway through; examine logs to determine if it's a heap limit, CPU limit, or data-related issue, then guide the fix.
- Performance regression after a code change; compare debug logs before and after to isolate the new bottleneck and recommend remediation.
- Salesforce developers troubleshooting Apex runtime failures and performance issues
- Platform engineers diagnosing governor-limit violations in production or test orgs
- QA engineers analyzing test failures via debug logs to report root causes to developers
- Architects reviewing performance telemetry to guide optimization priorities
platform-apex-logs-debug FAQ
Use platform-apex-logs-debug for diagnosis and root-cause analysis of debug logs. Delegate to platform-apex-generate when you need to implement or rewrite Apex code, and to platform-apex-test-run when you need to execute or repair test classes.
Reduce debug levels (e.g., set ApexCode to INFO and ApexProfiling to FINE) and re-capture the log. Alternatively, narrow the transaction window or user scope to keep the log within size limits.
Always check the LIMIT_USAGE events in the log to see actual consumption. Limits may be consumed by earlier operations not visible at the failure point. Compare sync limits (10,000 ms CPU, 6 MB heap) to async limits (60,000 ms CPU, 12 MB heap) based on transaction type.
Walk up the call stack past trigger handlers and framework code to find the originating user code. The root cause is typically in your business logic, not the framework.
Re-run the same transaction with a fresh debug log enabled. Compare the new log to the original: governor-limit usage should drop, repeated SOQL/DML patterns should disappear, and CPU/heap pressure should decrease.
Full instructions (SKILL.md)
Source of truth, from forcedotcom/sf-skills.
name: platform-apex-logs-debug 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 platform-apex-test-run), generating or fixing Apex code (use platform-apex-generate), or Agentforce session tracing (use agentforce-observe)." metadata: version: "1.1" domains: ["Platform"] relatedSkills: - "agentforce-observe" - "platform-apex-generate" - "platform-apex-test-run" - "platform-data-manage" - "platform-metadata-deploy" - "platform-soql-query" cliTools: - tool: ["sf"] semver: ">=2.0.0" - tool: ["jq"] semver: ">=1.6.0"
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:
.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 → platform-apex-test-run
- generating or implementing the code fix → platform-apex-generate
- debugging Agentforce session traces / parquet telemetry → 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
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
| Need | Delegate to | Reason |
|---|---|---|
| Implement Apex fix | platform-apex-generate | code change generation / review |
| Reproduce via tests | platform-apex-test-run | test execution and coverage loop |
| Deploy fix | platform-metadata-deploy | deployment orchestration |
| Create debugging data | platform-data-manage | 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.
platform-apex-test-generate
Generate and validate Apex test classes with TestDataFactory patterns, bulk testing, mocking, and coverage analysis.
platform-apex-test-run
Run Apex tests, analyze coverage, and fix failures in Salesforce with structured test-fix loops.
platform-architecture-analyze
Holistic Well-Architected review of Salesforce DX projects: grades observable code/metadata criteria and emits governance checklist.
platform-capability-search
Discover Salesforce capabilities and plugins matched to your task or journey stage.
platform-custom-application-generate
Create and configure tab-based Salesforce Lightning Custom Applications with navigation, branding, and action overrides.
platform-custom-field-generate
Generate and validate Salesforce Custom Field metadata XML with built-in constraints for Roll-Up Summary and Master-Detail relationships.