salesforce-apex-log-analyzer-skill

salesforce-apex-log-analyzer-skill

T1 read-only runtime skill for Apex debug log retrieval and analysis. This skill is a diagnostic flashlight — it retrieves log content, identifies governor-limit hits, surfaces SOQL N+1 patterns, traces exceptions, and produces a prioritized finding report. It does not execute code, mutate data, or deploy anything.

When This Skill Owns the Task

Use salesforce-apex-log-analyzer-skill when the work requires log-based diagnosis:

• "Why is my Account trigger hitting a governor limit?"
• "Analyze the debug log from my sandbox — it shows a heap size limit"
• "This trigger is slow — can you read the log and find the SOQL bottleneck?"
• "I got an unhandled exception in my batch job — here is the log"
• "Check if my Queueable is completing successfully in the async log"
• "Retrieve the latest log for user jsmith@myorg.sandbox and diagnose it"

Delegate elsewhere when:

| Situation | Skill to use | |---|---| | User wants to run Apex tests (not read logs) | salesforce-apex-test-runner-skill | | Static code review without log evidence | salesforce-apex-lwc-code-review-skill | | Generate a fix for the identified code problem | salesforce-apex-generator-skill | | Agentforce session traces / parquet telemetry | salesforce-agentforce-stdm-observer-skill | | SOQL query performance analysis without logs | salesforce-soql-explorer-skill |

Required Context to Gather First

Before retrieving or analyzing any log, confirm:

1. Target org alias — the --target-org value from sf org list.
2. Log identifier — log ID, log file path, user/transaction context, or timeframe.

Accept a pasted log file if the user provides one directly.

1. Transaction context — which trigger, class, batch job, or user action generated the log.
2. Goal — governor-limit diagnosis, exception trace, performance analysis, or all.
3. Sensitivity level — does the log likely contain PII (email, phone, record data from

regulated objects)? Apply stricter redaction if so.

Recommended Workflow

Step 1 — Verify org alias and reachability

sf org display --target-org <alias>

Confirm the org is reachable. Note org type (production vs sandbox) for the audit envelope. Apply stricter scrutiny for production org logs — log content may contain PII.

Step 2 — List available logs

sf apex get log --list --target-org <alias>

Identify the relevant log(s) by user, timestamp, and log type. If the user provides a log ID, skip this step and proceed to Step 3.

Step 3 — Retrieve the log

Option A — specific log by ID:

sf apex get log \
  --log-id <logId> \
  --target-org <alias>

Option B — latest log for current user:

sf apex get log \
  --number 1 \
  --target-org <alias>

Option C — tail live logs (non-blocking diagnostic):

sf apex tail log \
  --target-org <alias> \
  --color

Option D — user has pasted log content directly: Accept the pasted content and proceed to Step 4.

Step 4 — Parse the log in order

Analyze in this sequence per references/log-format-reference.md:

1. Entry point — identify transaction type (Apex class invocation, trigger, REST callout, batch execute)
2. Fatal errors and unhandled exceptions — FATAL_ERROR and EXCEPTION_THROWN lines
3. Governor limit hits — LIMIT_USAGE_FOR_NS entries; compare to limits in references/governor-limit-signatures.md
4. SOQL patterns — SOQL_EXECUTE_BEGIN / SOQL_EXECUTE_END pairs; look for repeated queries in loop context
5. DML patterns — DML_BEGIN / DML_END pairs; check for loop context
6. CPU hotspots — high cumulative CPU entries; identify top consumers
7. Heap usage — HEAP_ALLOCATE patterns; identify large collection accumulation
8. Async job indicators — ENTERING_MANAGED_PKG, CALLOUT_REQUEST, FUTURE_CALL_PROCESS

Step 5 — Classify findings by severity

| Severity | Criteria | |---|---| | Critical | Runtime failure, hard limit hit, unhandled exception, data corruption risk | | Warning | Near-limit (>75% of a governor limit), non-selective SOQL, slow DML path | | Info | Optimization opportunity, hygiene issue, async pattern note |

Step 6 — Apply redaction

Apply all redaction rules (see Redaction Rules section) before emitting any log excerpt in output. Never echo raw log lines containing record IDs, user IDs, or PII field values.

Step 7 — Emit findings with audit envelope

Score findings against the quality rubric (see below). Emit the full audit envelope. Propose the smallest correct fix for each Critical and Warning finding.

Step 8 — Route to repair skill

If a code fix is needed, hand off to salesforce-apex-generator-skill with the specific finding as context. If a deeper test run is needed, route to salesforce-apex-test-runner-skill.

Quality Scoring Rubric (100-point)

Score the analysis quality before presenting. Threshold: 80+ acceptable.

| Dimension | Points | What earns full marks | |---|---|---| | Governor-limit identification | 25 | All governor limit hits identified with limit name, current value, and limit ceiling; near-limit warnings included | | Root cause clarity | 25 | Each finding traces to a specific class, method, and line number; not just "SOQL limit hit" but "AccountSelector.getByOwner line 45 in loop at TriggerHandler line 12" | | SOQL N+1 detection | 15 | Repeated SOQL_EXECUTE_BEGIN entries in loop context identified and the responsible pattern named | | Sanitization quality | 15 | All record IDs, user IDs, and PII values redacted in output; no raw log lines echoed; audit envelope populated | | Handoff routing | 10 | Each Critical/Warning finding includes a specific next action and the skill to route to | | Audit envelope | 10 | All required fields present; log ID hashed if PII risk; timestamp accurate |

Scoring penalties:

• Raw log lines with record IDs echoed: -20 (immediate caveat)
• Governor limit hit identified but not traced to source: -15
• SOQL in loop not flagged: -15
• Missing audit envelope: -15
• PII field values in output: score voided (immediate reject)

T1 Least-Privilege Contract

This skill operates at T1 — read-only runtime.

• OAuth scopes: api and refresh_token only.
• Run As account permissions:
• REQUIRED: View Setup and Configuration
• DENIED: ModifyAllData, ViewAllData, ViewEncryptedData, ModifyMetadata,

AuthorApex, ManageConnectedApps

• No View All Data: Unlike the test runner skill, this skill does NOT require

View All Data. Log retrieval uses sf apex get log which operates under the View Setup and Configuration permission scope.

• Read-only: Retrieves log content only. No code execution, no DML, no metadata change.
• Log content sensitivity: Debug logs may contain field values from records processed

during the transaction. Apply PII redaction rules strictly.

Audit Envelope Schema

audit_envelope:
  matter_id: "<caller-provided-or-generated-uuid>"
  skill_id: "salesforce-apex-log-analyzer-skill"
  skill_version: "0.1.0"
  target_org_alias: "<alias>"
  run_as_user_id: "<user_id_placeholder>"
  org_type_verified: "sandbox | production | unknown"
  log_id: "<log-id-or-hash-if-pii-risk>"
  log_size_bytes: <integer>
  transaction_entry_point: "<class or trigger name>"
  timestamp: "<ISO-8601-UTC>"
  pii_risk_assessed: true | false
  redactions_applied:
    - field_or_pattern: "<pattern>"
      reason: "<record_id|user_id|pii|session_token>"
  findings_count:
    critical: <integer>
    warning: <integer>
    info: <integer>

Output Format

verdict: "acceptable | caveat | reject"
quality_score: <0-100>
quality_notes: "<scoring rationale>"

transaction_summary:
  entry_point: "<class/trigger/batch>"
  transaction_type: "<trigger|class|batch|queueable|schedulable|rest>"
  org_alias: "<al