forcedotcom/sf-skills / plugins/builder/salesforce-development/skills/platform-apex-logs-debug
platform-apex-logs-debug
VerifiedSalesforce 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).
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 2.2 KB |
| SKILL.md | skill md | 7.7 KB |
| assets/benchmarking-template.cls | other | 14.7 KB |
| assets/cpu-heap-optimization.cls | other | 11.8 KB |
| assets/dml-in-loop-fix.cls | other | 8.6 KB |
| assets/null-pointer-fix.cls | other | 10.4 KB |
| assets/soql-in-loop-fix.cls | other | 6.3 KB |
| references/analysis-playbook.md | markdown | 1.3 KB |
| references/benchmarking-guide.md | markdown | 7.7 KB |
| references/cli-commands.md | markdown | 8.9 KB |
| references/common-issues.md | markdown | 1.2 KB |
| references/debug-log-reference.md | markdown | 8.5 KB |
| references/log-analysis-tools.md | markdown | 7.1 KB |
| references/scoring-rubric.md | markdown | 821 B |
references/debug-log-reference.md
View on GitHub<!-- Parent: platform-apex-logs-debug/SKILL.md -->
# Salesforce Debug Log Reference
## Log Structure
Debug logs follow a consistent format:
```text
TIMESTAMP|EVENT_IDENTIFIER|[PARAMS]|DETAILS
```
Example:
```text
14:32:54.123 (123456789)|SOQL_EXECUTE_BEGIN|[45]|SELECT Id FROM Account
```
---
## Event Categories
### Execution Events
| Event | Description | Analysis Notes |
|-------|-------------|----------------|
| `EXECUTION_STARTED` | Transaction begins | Identifies transaction type |
| `EXECUTION_FINISHED` | Transaction ends | Total execution time |
| `CODE_UNIT_STARTED` | Method/trigger entry | Call stack tracing |
| `CODE_UNIT_FINISHED` | Method/trigger exit | Method duration |
### SOQL Events
| Event | Description | Key Fields |
|-------|-------------|------------|
| `SOQL_EXECUTE_BEGIN` | Query starts | Line number, Query text |
| `SOQL_EXECUTE_END` | Query ends | Rows returned |
**Analysis Pattern:**
```text
|SOQL_EXECUTE_BEGIN|[45]|SELECT Id, Name FROM Account WHERE...
|SOQL_EXECUTE_END|[3 rows]
```
- Line 45 in source code
- Query returned 3 rows
**Warning Signs:**
- Same query appearing multiple times → SOQL in loop
- `[100000 rows]` → Non-selective query
- Query without WHERE clause → Full table scan
### DML Events
| Event | Description | Key Fields |
|-------|-------------|------------|
| `DML_BEGIN` | DML starts | Line number, Operation type, Object |
| `DML_END` | DML ends | Rows affected |
**Analysis Pattern:**
```text
|DML_BEGIN|[78]|Op:Insert|Type:Contact|
|DML_END|[200 rows]
```
- Line 78: INSERT operation
- 200 Contact records inserted
**Warning Signs:**
- Same DML operation appearing multiple times → DML in loop
- DML after each SOQL → Likely unbulkified code
### Limit Events
| Event | Description | Format |
|-------|-------------|--------|
| `LIMIT_USAGE` | Current limit usage | `LIMIT_NAME|used|max` |
| `LIMIT_USAGE_FOR_NS` | Per-namespace limits | `LIMIT_NAME|used|max|namespace` |
| `CUMULATIVE_LIMIT_USAGE` | End of transaction | Summary of all limits |
**Example:**
```text
|LIMIT_USAGE|SOQL_QUERIES|25|100
|LIMIT_USAGE|DML_STATEMENTS|45|150
|LIMIT_USAGE|CPU_TIME|3500|10000
|LIMIT_USAGE|HEAP_SIZE|2500000|6000000
```
### Exception Events
| Event | Description | Format |
|-------|-------------|--------|
| `EXCEPTION_THROWN` | Exception occurs | `[line]|ExceptionType|Message` |
| `FATAL_ERROR` | Unhandled exception | Full stack trace |
**Analysis Pattern:**
```text
|EXCEPTION_THROWN|[67]|System.NullPointerException|Attempt to de-reference a null object
|FATAL_ERROR|System.NullPointerException: Attempt to de-reference a null object
Class.ContactService.processContacts: line 67, column 1
Class.AccountTriggerHandler.afterUpdate: line 34, column 1
Trigger.AccountTrigger: line 5, column 1
```
### Method Events
| Event | Description | Use Case |
|-------|-------------|----------|
| `METHOD_ENTRY` | Method called | Call hierarchy |
| `METHOD_EXIT` | Method returns | Method duration |
| `CONSTRUCTOR_ENTRY` | Constructor called | Object creation |
| `CONSTRUCTOR_EXIT` | Constructor returns | |
### Loop Events
| Event | Description | Important For |
|-------|-------------|---------------|
| `LOOP_BEGIN` | Loop starts | SOQL/DML in loop detection |
| `LOOP_END` | Loop ends | |
| `ITERATION_BEGIN` | Loop iteration | Iteration count |
| `ITERATION_END` | Iteration ends | |
**Detection Pattern for SOQL in Loop:**
```text
|LOOP_BEGIN|
|ITERATION_BEGIN|
|SOQL_EXECUTE_BEGIN|[45]|SELECT...
|SOQL_EXECUTE_END|[1 rows]
|ITERATION_END|
|ITERATION_BEGIN|
|SOQL_EXECUTE_BEGIN|[45]|SELECT... ← Same query repeating!
|SOQL_EXECUTE_END|[1 rows]
|ITERATION_END|
|LOOP_END|
```
### Callout Events
| Event | Description | Key Fields |
|-------|-------------|------------|
| `CALLOUT_EXTERNAL_ENTRY` | HTTP callout starts | Endpoint URL |
| `CALLOUT_EXTERNAL_EXIT` | HTTP callout ends | Status code, Duration |
**Example:**
```text
|CALLOUT_EXTERNAL_ENTRY|[89]|https://api.example.com/endpoint
|CALLOUT_EXTERNAL_EXIT|[200]|[1500ms]
```
### Heap Events
| Event | Description | Importance |
|-------|-------------|------------|
| `HEAP_ALLOCATE` | Heap allocation | Track large allocations |
| `HEAP_DEALLOCATE` | Heap freed | Garbage collection |
---
## Log Levels
### Categories and Levels
| Category | What It Controls |
|----------|------------------|
| Database | SOQL, SOSL, DML |
| Workflow | Workflow rules, Process Builder |
| Validation | Validation rules |
| Callout | HTTP callouts |
| Apex Code | Apex execution |
| Apex Profiling | Method timing |
| Visualforce | VF page execution |
| System | System operations |
### Level Values
| Level | Amount of Detail | Use Case |
|-------|------------------|----------|
| NONE | Nothing | Disable category |
| ERROR | Errors only | Production monitoring |
| WARN | Warnings + errors | |
| INFO | General info | Default |
| DEBUG | Detailed debug | Development |
| FINE | Very detailed | Deep debugging |
| FINER | Method entry/exit | Performance analysis |
| FINEST | Everything | Complete trace |
### Recommended Debug Level Settings
**For Performance Issues:**
```text
Apex Code: FINE
Apex Profiling: FINEST
Database: FINE
System: DEBUG
```
**For Exception Debugging:**
```text
Apex Code: DEBUG
Apex Profiling: FINE
Database: INFO
System: DEBUG
```
**For Callout Issues:**
```text
Apex Code: DEBUG
Callout: FINEST
System: DEBUG
```
---
## Governor Limits Reference
### Synchronous Limits
| Limit | Value | Log Event |
|-------|-------|-----------|
| SOQL Queries | 100 | `SOQL_QUERIES` |
| SOQL Rows | 50,000 | `SOQL_ROWS` |
| DML Statements | 150 | `DML_STATEMENTS` |
| DML Rows | 10,000 | `DML_ROWS` |
| CPU Time | 10,000 ms | `CPU_TIME` |
| Heap Size | 6 MB | `HEAP_SIZE` |
| Callouts | 100 | `CALLOUTS` |
| Future Calls | 50 | `FUTURE_CALLS` |
### Asynchronous Limits
| Limit | Value | Applies To |
|-------|-------|------------|
| CPU Time | 60,000 ms | @future, Batch, Queueable |
| Heap Size | 12 MB | @future, Batch, Queueable |
### Warning Thresholds
| Limit | Warning (80%) | Critical (95%) |
|-------|---------------|----------------|
| SOQL Queries | 80 | 95 |
| DML Statements | 120 | 143 |
| CPU Time | 8,000 ms | 9,500 ms |
| Heap Size | 4.8 MB | 5.7 MB |
---
## Common Log Patterns
### Pattern 1: SOQL in Loop
```text
|LOOP_BEGIN|
|ITERATION_BEGIN|
|SOQL_EXECUTE_BEGIN|[45]|SELECT Id FROM Contact WHERE AccountId = '001xxx'
|SOQL_EXECUTE_END|[1 rows]
|ITERATION_END|
|ITERATION_BEGIN|
|SOQL_EXECUTE_BEGIN|[45]|SELECT Id FROM Contact WHERE AccountId = '001yyy'
|SOQL_EXECUTE_END|[1 rows]
|ITERATION_END|
... (repeats 100 times)
|LIMIT_USAGE|SOQL_QUERIES|100|100 ← LIMIT HIT!
|FATAL_ERROR|System.LimitException: Too many SOQL queries: 101
```
### Pattern 2: DML in Loop
```text
|LOOP_BEGIN|
|ITERATION_BEGIN|
|DML_BEGIN|[78]|Op:Insert|Type:Contact|
|DML_END|[1 rows]
|ITERATION_END|
... (repeats 150 times)
|LIMIT_USAGE|DML_STATEMENTS|150|150 ← LIMIT HIT!
|FATAL_ERROR|System.LimitException: Too many DML statements: 151
```
### Pattern 3: Non-Selective Query
```text
|SOQL_EXECUTE_BEGIN|[23]|SELECT Id FROM Lead WHERE Status = 'Open'
|SOQL_EXECUTE_END|[250000 rows] ← Large result set!
```
### Pattern 4: CPU Limit Approaching
```text
|CUMULATIVE_LIMIT_USAGE|
|CPU_TIME|9500|10000 ← 95% used!
```
### Pattern 5: Null Pointer Exception
```text
|SOQL_EXECUTE_BEGIN|[45]|SELECT Id FROM Account WHERE Id = '001xxx'
|SOQL_EXECUTE_END|[0 rows] ← No results!
|METHOD_EXIT|getAccount|
|EXCEPTION_THROWN|[47]|System.NullPointerException|Attempt to de-reference a null object
```
---
## Log Analysis Checklist
### Quick Scan
1. **Search for `FATAL_ERROR`** - Find the exception
2. **Search for `LIMIT_USAGE`** - Check governor limits
3. **Search for `SOQL_EXECUTE_BEGIN`** - Count queries
4. **Search for `DML_BEGIN`** - Count DML operations
5. **Search for `LOOP_BEGIN`** - Check for operations in loops
### Deep Analysis
1. **Trace the call stack** - Use `CODE_UNIT_STARTED` events
2. **Find the hotspot** - Use `Apex Profiling: FINEST` for method timing
3. **Identify large queries** - Look for `[N rows]` in SOQL_EXECUTE_END
4. **Check callout timing** - Look for slow `CALLOUT_EXTERNAL_EXIT`
5. **Monitor heap growth** - Track `HEAP_ALLOCATE` events
---
## Related Commands
| Command | Purpose |
|---------|---------|
| `sf apex list log` | List available logs |
| `sf apex get log --log-id XXX` | Download specific log |
| `sf apex tail log` | Stream logs real-time |
| `sf data delete record --sobject ApexLog --record-id <id>` | Delete individual log record |
See [cli-commands.md](./cli-commands.md) for detailed command reference.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |