@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/debugging-apex-logs/references/benchmarking-guide.md

@@ -0,0 +1,287 @@
+<!-- Parent: debugging-apex-logs/SKILL.md -->
+# Apex Benchmarking Guide
+
+Performance testing is essential for writing efficient Apex code. This guide covers reliable benchmarking techniques and real-world performance data based on established Apex community practices and Salesforce governor limit behavior.
+
+---
+
+## Why Benchmark?
+
+"Premature optimization is the root of all evil" - but **informed optimization** is essential. Benchmarking answers:
+
+1. **Which approach is faster?** (Loop styles, data structures)
+2. **Will this scale?** (200 records vs 10,000)
+3. **Where are the bottlenecks?** (CPU, heap, SOQL)
+
+---
+
+## Apex Benchmarking Technique
+
+The recommended approach for reliable Apex performance testing:
+
+### The Pattern
+
+```apex
+// Run in Anonymous Apex for consistent environment
+Long startTime = System.currentTimeMillis();
+
+// Your code to benchmark
+for (Integer i = 0; i < 10000; i++) {
+    // Operation being tested
+}
+
+Long endTime = System.currentTimeMillis();
+System.debug('Duration: ' + (endTime - startTime) + 'ms');
+```
+
+### Key Principles
+
+| Principle | Why It Matters |
+|-----------|----------------|
+| **Use Anonymous Apex** | Consistent execution environment, no trigger interference |
+| **Run Multiple Iterations** | Averages out JIT compilation and garbage collection |
+| **Test at Scale** | 200 records ≠ 10,000 records in terms of performance |
+| **Isolate the Operation** | Test one thing at a time |
+| **Run Multiple Times** | First run often slower due to JIT compilation |
+
+### Example: Complete Benchmark
+
+```apex
+// Comprehensive benchmark template
+public class BenchmarkRunner {
+
+    public static void compareMethods() {
+        Integer iterations = 10000;
+
+        // Warm-up run (JIT compilation)
+        warmUp();
+
+        // Method A
+        Long startA = System.currentTimeMillis();
+        for (Integer i = 0; i < iterations; i++) {
+            methodA();
+        }
+        Long durationA = System.currentTimeMillis() - startA;
+
+        // Method B
+        Long startB = System.currentTimeMillis();
+        for (Integer i = 0; i < iterations; i++) {
+            methodB();
+        }
+        Long durationB = System.currentTimeMillis() - startB;
+
+        // Results
+        System.debug('Method A: ' + durationA + 'ms');
+        System.debug('Method B: ' + durationB + 'ms');
+        System.debug('Difference: ' + Math.abs(durationA - durationB) + 'ms');
+        System.debug('Winner: ' + (durationA < durationB ? 'Method A' : 'Method B'));
+    }
+
+    private static void warmUp() {
+        for (Integer i = 0; i < 100; i++) {
+            methodA();
+            methodB();
+        }
+    }
+
+    private static void methodA() { /* Implementation A */ }
+    private static void methodB() { /* Implementation B */ }
+}
+```
+
+---
+
+## Real-World Benchmark Results
+
+### String Concatenation vs String.join()
+
+From documented Apex benchmarks:
+
+| Method | Records | Duration | Result |
+|--------|---------|----------|--------|
+| String `+=` in loop | 1,750 | 11,767ms | CPU LIMIT HIT |
+| `String.join()` | 7,500 | 539ms | Still running |
+| **Improvement** | - | **22x faster** | - |
+
+```apex
+// ❌ SLOW: String concatenation in loop (O(n²) string copies)
+String result = '';
+for (Account acc : accounts) {
+    result += acc.Name + '\n';  // Creates new string each time!
+}
+
+// ✅ FAST: String.join() (O(n) single allocation)
+List<String> names = new List<String>();
+for (Account acc : accounts) {
+    names.add(acc.Name);
+}
+String result = String.join(names, '\n');
+```
+
+### Loop Performance Comparison
+
+From documented Apex loop benchmarks (10,000 iterations):
+
+| Loop Type | Duration | Notes |
+|-----------|----------|-------|
+| While loop | ~0.4s | Fastest |
+| Cached iterator | ~0.8s | Good alternative |
+| For loop (index) | ~1.4s | Acceptable |
+| Enhanced for-each | ~2.4s | Convenient but slower |
+| Uncached iterator | CPU LIMIT | Avoid |
+
+```apex
+// 🏆 FASTEST: While loop
+Iterator<Account> iter = accounts.iterator();
+while (iter.hasNext()) {
+    Account acc = iter.next();
+    // process
+}
+
+// ✅ GOOD: Traditional for loop
+for (Integer i = 0; i < accounts.size(); i++) {
+    Account acc = accounts[i];
+    // process
+}
+
+// ⚠️ CONVENIENT BUT SLOWER: Enhanced for-each
+for (Account acc : accounts) {
+    // process - OK for small collections
+}
+```
+
+### Map vs List Lookup
+
+| Operation | Complexity | 10,000 lookups |
+|-----------|------------|----------------|
+| List.contains() | O(n) | ~500ms |
+| Set.contains() | O(1) | ~5ms |
+| Map.containsKey() | O(1) | ~5ms |
+
+```apex
+// ❌ SLOW: List lookup
+List<Id> processedIds = new List<Id>();
+for (Account acc : accounts) {
+    if (!processedIds.contains(acc.Id)) {  // O(n) each time!
+        processedIds.add(acc.Id);
+    }
+}
+
+// ✅ FAST: Set lookup
+Set<Id> processedIds = new Set<Id>();
+for (Account acc : accounts) {
+    if (!processedIds.contains(acc.Id)) {  // O(1) constant time
+        processedIds.add(acc.Id);
+    }
+}
+```
+
+---
+
+## Governor Limit Ceilings
+
+### Official Limits
+
+| Limit | Synchronous | Asynchronous |
+|-------|-------------|--------------|
+| CPU Time | 10,000 ms | 60,000 ms |
+| Heap Size | 6 MB | 12 MB |
+| SOQL Queries | 100 | 200 |
+| DML Statements | 150 | 150 |
+
+### Practical Thresholds
+
+| Limit | Warning (80%) | Critical (95%) |
+|-------|---------------|----------------|
+| CPU Time | 8,000 ms | 9,500 ms |
+| Heap Size | 4.8 MB | 5.7 MB |
+| SOQL Queries | 80 | 95 |
+
+### Runtime Limit Checking
+
+```apex
+public void processWithSafety(List<Account> accounts) {
+    Integer cpuWarning = 8000;
+    Integer heapWarning = 4800000;
+
+    for (Account acc : accounts) {
+        // Check before each operation
+        if (Limits.getCpuTime() > cpuWarning) {
+            System.debug(LoggingLevel.WARN,
+                'CPU approaching limit: ' + Limits.getCpuTime() + 'ms');
+            // Consider switching to async or chunking
+            break;
+        }
+
+        if (Limits.getHeapSize() > heapWarning) {
+            System.debug(LoggingLevel.WARN,
+                'Heap approaching limit: ' + Limits.getHeapSize() + ' bytes');
+            break;
+        }
+
+        processAccount(acc);
+    }
+}
+```
+
+---
+
+## Benchmarking Anti-Patterns
+
+### ❌ Don't Do These
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| Testing in triggers | Inconsistent environment | Use Anonymous Apex |
+| Single iteration | JIT variance affects results | Run 1000+ iterations |
+| Testing with 10 records | Doesn't reveal O(n²) issues | Test with 200+ records |
+| Ignoring warm-up | First run skewed by JIT | Add warm-up phase |
+| Mixing operations | Can't isolate bottleneck | Test one thing at a time |
+
+---
+
+## Benchmarking Checklist
+
+Before optimizing, verify:
+
+- [ ] Ran benchmark multiple times (3-5 runs)
+- [ ] Used 1000+ iterations for micro-benchmarks
+- [ ] Tested with production-scale data (200+ records)
+- [ ] Included warm-up phase
+- [ ] Ran in Anonymous Apex (not test context)
+- [ ] Compared both approaches fairly
+- [ ] Considered readability trade-offs
+
+---
+
+## When NOT to Optimize
+
+Sometimes clarity beats performance:
+
+```apex
+// More readable, negligible performance difference for small collections
+for (Account acc : accounts) {
+    acc.Description = acc.Name + ' - Updated';
+}
+
+// vs micro-optimized but harder to read
+Iterator<Account> iter = accounts.iterator();
+while (iter.hasNext()) {
+    Account acc = iter.next();
+    acc.Description = acc.Name + ' - Updated';
+}
+```
+
+**Rule of thumb**: Optimize when:
+1. Processing 200+ records regularly
+2. Approaching governor limits
+3. User experience is affected
+4. Benchmarks show measurable improvement
+
+---
+
+## Related Resources
+
+- [assets/benchmarking-template.cls](../assets/benchmarking-template.cls) - Ready-to-use benchmark template
+- [assets/cpu-heap-optimization.cls](../assets/cpu-heap-optimization.cls) - Optimization patterns
+- [Apex Log Analyzer](./log-analysis-tools.md) - Visual performance analysis

package/skills/debugging-apex-logs/references/cli-commands.md

@@ -0,0 +1,368 @@
+<!-- Parent: debugging-apex-logs/SKILL.md -->
+# Salesforce CLI Debug Commands Reference
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| List recent logs | `sf apex list log --target-org my-org` |
+| Get specific log | `sf apex get log --log-id 07Lxx0000000000` |
+| Stream real-time | `sf apex tail log --target-org my-org` |
+| Delete log | `sf data delete record --sobject ApexLog --record-id <id> --target-org my-org` |
+
+---
+
+## Log Retrieval
+
+### List Available Logs
+
+```bash
+# List all logs for current user
+sf apex list log --target-org my-org
+
+# JSON output for parsing
+sf apex list log --target-org my-org --json
+```
+
+**Output Fields:**
+- `Id` - Log ID for retrieval
+- `LogUser.Name` - Who generated the log
+- `Operation` - What triggered the log
+- `Status` - Success/Failure
+- `LogLength` - Size in bytes
+- `StartTime` - When it was generated
+
+### Get Specific Log
+
+```bash
+# Download log by ID
+sf apex get log \
+  --log-id 07Lxx0000000000AAA \
+  --target-org my-org
+
+# Save to file
+sf apex get log \
+  --log-id 07Lxx0000000000AAA \
+  --target-org my-org \
+  --output-dir ./logs
+
+# Get most recent log
+sf apex list log --target-org my-org --json | \
+  jq -r '.result[0].Id' | \
+  xargs -I {} sf apex get log --log-id {} --target-org my-org
+```
+
+### Stream Logs Real-Time
+
+```bash
+# Tail logs with color highlighting
+sf apex tail log --target-org my-org --color
+
+# Tail with color highlighting
+sf apex tail log \
+  --target-org my-org \
+  --color
+# Note: Debug levels are configured via TraceFlag records in Setup, not CLI flags
+
+# Tail with skip flag (don't show historical logs)
+sf apex tail log --target-org my-org --skip-trace-flag
+```
+
+---
+
+## Log Management
+
+### Delete Logs
+
+> **Note**: `sf apex log delete` does not exist in sf CLI v2. Use `sf data delete record` instead.
+
+```bash
+# Delete specific log
+sf data delete record \
+  --sobject ApexLog \
+  --record-id 07Lxx0000000000AAA \
+  --target-org my-org
+```
+
+---
+
+## Debug Level Configuration
+
+### Using Trace Flags
+
+Trace flags control what gets logged and for which users.
+
+```bash
+# Create trace flag for specific user
+sf data create record \
+  --sobject TraceFlag \
+  --values "TracedEntityId='005xx0000001234' LogType='USER_DEBUG' DebugLevelId='7dlxx0000000000' StartDate='2025-01-01T00:00:00Z' ExpirationDate='2025-01-02T00:00:00Z'" \
+  --target-org my-org
+
+# Query existing trace flags
+sf data query \
+  --query "SELECT Id, TracedEntityId, DebugLevel.MasterLabel, ExpirationDate FROM TraceFlag" \
+  --target-org my-org
+
+# Delete trace flag
+sf data delete record \
+  --sobject TraceFlag \
+  --record-id 7tfxx0000000000AAA \
+  --target-org my-org
+```
+
+### Debug Levels
+
+```bash
+# List available debug levels
+sf data query \
+  --query "SELECT Id, MasterLabel, ApexCode, ApexProfiling, Callout, Database, System, Workflow FROM DebugLevel" \
+  --target-org my-org
+
+# Create custom debug level
+sf data create record \
+  --sobject DebugLevel \
+  --values "MasterLabel='PerformanceDebug' DeveloperName='PerformanceDebug' ApexCode='FINE' ApexProfiling='FINEST' Database='FINE' System='DEBUG'" \
+  --target-org my-org
+```
+
+---
+
+## Advanced Usage
+
+### Execute Anonymous with Logging
+
+```bash
+# Run anonymous Apex and capture log
+echo "System.debug('Test'); Account a = [SELECT Id FROM Account LIMIT 1];" | \
+  sf apex run --target-org my-org
+
+# Run from file
+sf apex run \
+  --file ./scripts/debug-script.apex \
+  --target-org my-org
+
+# Get the log from that execution
+sf apex list log --target-org my-org --json | \
+  jq -r '.result[0].Id' | \
+  xargs -I {} sf apex get log --log-id {} --target-org my-org
+```
+
+### Query Plan Analysis
+
+```bash
+# Analyze query plan using Tooling API
+sf data query \
+  --query "SELECT Id FROM Account WHERE Name = 'Test'" \
+  --target-org my-org \
+  --use-tooling-api
+# Note: --explain does not exist. Use REST API for query plans:
+# GET /services/data/v66.0/query/?explain=SELECT+Id+FROM+Account+WHERE+Name='Test'
+```
+
+### Log Analysis with grep
+
+```bash
+# Find SOQL queries in log
+sf apex get log --log-id 07Lxx0000000000 --target-org my-org | \
+  rg "SOQL_EXECUTE"
+
+# Count SOQL queries
+sf apex get log --log-id 07Lxx0000000000 --target-org my-org | \
+  rg -c "SOQL_EXECUTE_BEGIN"
+
+# Find exceptions
+sf apex get log --log-id 07Lxx0000000000 --target-org my-org | \
+  rg "EXCEPTION_THROWN|FATAL_ERROR"
+
+# Find limit usage
+sf apex get log --log-id 07Lxx0000000000 --target-org my-org | \
+  rg "LIMIT_USAGE"
+
+# Find slow operations (method timing)
+sf apex get log --log-id 07Lxx0000000000 --target-org my-org | \
+  rg "METHOD_EXIT.*\|([0-9]{4,})\|"
+```
+
+---
+
+## Automation Scripts
+
+### Save and Analyze Latest Log
+
+```bash
+#!/bin/bash
+# save-latest-log.sh
+
+ORG_ALIAS=${1:-"my-org"}
+OUTPUT_DIR=${2:-"./logs"}
+
+mkdir -p $OUTPUT_DIR
+
+# Get latest log ID
+LOG_ID=$(sf apex list log --target-org $ORG_ALIAS --json | jq -r '.result[0].Id')
+
+if [ "$LOG_ID" == "null" ]; then
+    echo "No logs found"
+    exit 1
+fi
+
+# Save log
+FILENAME="$OUTPUT_DIR/$(date +%Y%m%d_%H%M%S)_$LOG_ID.log"
+sf apex get log --log-id $LOG_ID --target-org $ORG_ALIAS > $FILENAME
+
+echo "Log saved to: $FILENAME"
+
+# Quick analysis
+echo ""
+echo "=== QUICK ANALYSIS ==="
+echo "SOQL Queries: $(rg -c 'SOQL_EXECUTE_BEGIN' $FILENAME || echo 0)"
+echo "DML Statements: $(rg -c 'DML_BEGIN' $FILENAME || echo 0)"
+echo "Exceptions: $(rg -c 'EXCEPTION_THROWN|FATAL_ERROR' $FILENAME || echo 0)"
+```
+
+### Monitor for Errors
+
+```bash
+#!/bin/bash
+# monitor-errors.sh
+
+ORG_ALIAS=${1:-"my-org"}
+
+echo "Monitoring $ORG_ALIAS for errors..."
+echo "Press Ctrl+C to stop"
+
+sf apex tail log --target-org $ORG_ALIAS --color 2>&1 | \
+  while read line; do
+    if echo "$line" | rg -q "EXCEPTION|FATAL_ERROR|LimitException"; then
+      echo "🔴 ERROR DETECTED: $line"
+      # Optional: Send alert
+      # osascript -e 'display notification "Error in Salesforce" with title "debugging-apex-logs"'
+    fi
+  done
+```
+
+### Bulk Log Cleanup
+
+```bash
+#!/bin/bash
+# cleanup-logs.sh
+
+ORG_ALIAS=${1:-"my-org"}
+DAYS_OLD=${2:-7}
+
+echo "Deleting logs older than $DAYS_OLD days from $ORG_ALIAS..."
+
+# Get old log IDs
+OLD_LOGS=$(sf data query \
+  --query "SELECT Id FROM ApexLog WHERE StartTime < LAST_N_DAYS:$DAYS_OLD" \
+  --target-org $ORG_ALIAS \
+  --json | jq -r '.result.records[].Id')
+
+COUNT=0
+for LOG_ID in $OLD_LOGS; do
+    sf data delete record --sobject ApexLog --record-id $LOG_ID --target-org $ORG_ALIAS --json > /dev/null
+    ((COUNT++))
+done
+
+echo "Deleted $COUNT logs"
+```
+
+---
+
+## Troubleshooting
+
+### No Logs Appearing
+
+1. **Check trace flags exist:**
+   ```bash
+   sf data query \
+     --query "SELECT Id, TracedEntityId, ExpirationDate FROM TraceFlag WHERE ExpirationDate > TODAY" \
+     --target-org my-org
+   ```
+
+2. **Check log retention:**
+   ```bash
+   sf data query \
+     --query "SELECT Id, StartTime FROM ApexLog ORDER BY StartTime DESC LIMIT 5" \
+     --target-org my-org
+   ```
+
+3. **Verify user has API access:**
+   - User must have "API Enabled" permission
+   - User must have "Author Apex" for trace flags
+
+### Log Too Large
+
+Logs over 2MB are truncated. Solutions:
+
+1. **Reduce debug level:**
+   ```
+   ApexCode: DEBUG → INFO
+   ApexProfiling: FINEST → FINE
+   ```
+
+2. **Focus on specific operation:**
+   - Create trace flag just before the operation
+   - Delete after capturing
+
+3. **Use targeted logging:**
+   - Add `System.debug()` only where needed
+   - Use `LoggingLevel.ERROR` for critical info
+
+### Logs Not Persisting
+
+Default log retention is 24 hours. To keep logs longer:
+
+```bash
+# Export log to file immediately
+sf apex get log --log-id 07Lxx0000000000 --target-org my-org > ./saved-log.txt
+```
+
+---
+
+## Integration with debugging-apex-logs Skill
+
+The debugging-apex-logs skill automatically:
+
+1. **Fetches logs** when you run `sf apex get log` or `sf apex tail log`
+2. **Parses content** for SOQL in loops, DML in loops, exceptions
+3. **Displays analysis** with governor limit usage
+4. **Suggests fixes** using sf-apex skill integration
+
+Example workflow:
+```bash
+# Run a test that generates a log
+sf apex run test --class-names MyTestClass --target-org my-org
+
+# Get the log (debugging-apex-logs hook auto-analyzes)
+sf apex list log --target-org my-org --json | \
+  jq -r '.result[0].Id' | \
+  xargs -I {} sf apex get log --log-id {} --target-org my-org
+```
+
+The hook will output analysis like:
+```
+============================================================
+🔍 DEBUG LOG ANALYSIS
+============================================================
+
+🔴 CRITICAL ISSUES
+------------------------------------------------------------
+   • SOQL in loop detected: 50 queries executed inside loops
+   • CPU limit critical: 9500/10000ms (95.0%)
+
+📊 GOVERNOR LIMIT USAGE
+------------------------------------------------------------
+   ✅ SOQL Queries: 50/100 (50.0%)
+   ✅ DML Statements: 25/150 (16.7%)
+   🔴 CPU Time (ms): 9500/10000 (95.0%)
+
+🤖 AGENTIC FIX RECOMMENDATIONS
+============================================================
+
+For SOQL in loop:
+   1. Move query BEFORE the loop
+   2. Store results in Map<Id, SObject>
+   3. Access from Map inside loop
+```

package/skills/debugging-apex-logs/references/common-issues.md

@@ -0,0 +1,68 @@
+# Common Debug Log Issues
+
+## SOQL in loop
+
+**Signals**
+- repeating `SOQL_EXECUTE_BEGIN`
+- query appears inside repeated method path
+
+**Fix pattern**
+- query once outside the loop
+- use `Map<Id, SObject>` or grouped collections
+
+## DML in loop
+
+**Signals**
+- repeated `DML_BEGIN`
+- high DML statement count for small transactions
+
+**Fix pattern**
+- collect changes
+- do one bulk DML operation
+
+## Non-selective query
+
+**Signals**
+- high rows scanned
+- slow query timing
+- table-scan indicators
+
+**Fix pattern**
+- add indexed filters
+- reduce scope
+- use query-plan guidance
+
+## CPU pressure
+
+**Signals**
+- CPU usage trending toward sync limit
+- repeated expensive helper methods
+- nested loops / repeated string work
+
+**Fix pattern**
+- reduce algorithmic complexity
+- cache repeated work
+- move heavy processing async where appropriate
+
+## Heap pressure
+
+**Signals**
+- large collection allocations
+- heap usage approaching sync limit
+
+**Fix pattern**
+- use SOQL for-loops
+- reduce in-memory object size
+- clear collections when done
+
+## Null pointer / unhandled exceptions
+
+**Signals**
+- `EXCEPTION_THROWN`
+- `FATAL_ERROR`
+- clear stack trace with line numbers
+
+**Fix pattern**
+- guard null values
+- make assumptions explicit
+- improve result handling for empty query results