debugging-apex-logs
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).
- Installs
- 3K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/forcedotcom/sf-skills --skill debugging-apex-logs- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads debugging-apex-logs automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 |
FAQ
What does the debugging-apex-logs skill do?
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).
How do I install debugging-apex-logs?
Run npx skills add https://github.com/forcedotcom/sf-skills --skill debugging-apex-logs in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/debugging-apex-logs/ (personal) or .claude/skills/debugging-apex-logs/ (project).
Which AI agents can use debugging-apex-logs?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is debugging-apex-logs safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains debugging-apex-logs?
It is published by forcedotcom in forcedotcom/sf-skills. It has 3,004 recorded installs.
More from forcedotcom/sf-skills
platform-apex-generate
forcedotcom/sf-skills
Primary Apex authoring skill for class generation, refactoring, and review. ALWAYS ACTIVATE when the user mentions Apex, .cls, triggers, or asks to create/refactor a class (service, selector, domain, batch, queueable, schedulable, invocable, DTO, utility, interface, abstract, exception, REST resource). Use this skill for requests involving SObject CRUD, mapping collections, fetching related records, scheduled jobs, batch jobs, trigger design, @AuraEnabled controllers, @RestResource endpoints, custom REST APIs, or code review of existing Apex.
platform-apex-test-generate
forcedotcom/sf-skills
Use to generate and validate Apex test classes with TestDataFactory patterns, bulk testing (251+ records), mocking, assertions, and disciplined test-fix loops. Use when creating Apex test classes (for triggers, services, controllers, batch jobs, queueables, and callouts), improving coverage, debugging or fixing failing Apex tests, or running test/coverage analysis. Triggers on Test.cls files, sf apex run test, coverage reports. Do NOT trigger for production Apex (use platform-apex-generate) or Jest/LWC tests.
platform-apex-test-run
forcedotcom/sf-skills
Apex test execution, coverage analysis, and test-fix loops with 120-point scoring. Use when the user runs Apex tests, checks code coverage, fixes failing tests, or touches Test.cls / Test.cls files. DO NOT TRIGGER when writing Apex production code (use platform-apex-generate), Agentforce agent testing (use agentforce-test), or Jest/LWC tests (use experience-lwc-generate).
platform-apex-logs-debug
forcedotcom/sf-skills
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).
platform-soql-query
forcedotcom/sf-skills
Use when the user needs SOQL/SOSL authoring or optimization: natural-language-to-query generation, relationship queries, aggregates, query-plan/selectivity analysis, and performance or safety improvements. TRIGGER when the user writes, optimizes, or debugs SOQL/SOSL, touches .soql files, or asks about relationship queries, aggregates, or query performance. DO NOT TRIGGER for bulk data operations (use platform-data-manage), Apex DML logic (use platform-apex-generate), or report/dashboard queries.
platform-metadata-deploy
forcedotcom/sf-skills
Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, validates a deploy or does a dry-run, deploys to a Production org, quick-deploys a validated job ID, ships/promotes to prod, creates/manages scratch orgs or sandboxes, sets up CI/CD pipelines, or troubleshoots deployment errors with sf project deploy. DO NOT TRIGGER when: writing Apex code, building LWC components (use experience-lwc-generate), creating metadata definitions (use platform-custom-object-generate), deleting metadata from an org (use platform-destructive-deploy), or querying org data (use platform-data-manage).
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.