@salesforce/afv-skills 1.22.0 → 1.23.0

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

@@ -1,287 +0,0 @@
-<!-- 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

@@ -1,368 +0,0 @@
-<!-- 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

@@ -1,68 +0,0 @@
-# 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