Salesforce Debug Log Analysis

Salesforce Debug Log Analysis

Salesforce debug logs look like text but behave like event traces from a distributed system. A single record update can produce tens of thousands of lines across dozens of triggers, flows, LWC controllers, rollup calculations, validation rules, workflow field updates, platform events, and managed packages. The real cause is often in a different transaction than the one the user uploaded, or inside a package whose source you cannot read. This skill captures the complete investigation pattern for every type of Salesforce runtime behavior.

Recommended Workflow

For any Salesforce log, follow this loop in order. Do not skip steps.

1. Triage: classify every uploaded log by size, start time, and shape before reading content.
2. Timeline: build a chronological view across all logs with inter-log deltas.
3. Classify the question: is the user asking about a flip-flop field, a failed DML, a slow transaction, a flow error, an async job, a merge, a permission issue, or something else? Each has a different investigation recipe.
4. Load the right reference: the references/ folder has dedicated guides for each major category. Load only what applies.
5. Execute the recipe: run the specific greps and Python extractions for that category.
6. Report with structure: headline, evidence, mechanism, limits, recommendations.

Step 1: triage every log

Before reading any content, run:

cd /mnt/user-data/uploads
ls -la *.log

for f in *.log; do
  start=$(head -3 "$f" | tail -1 | awk '{print $1}')
  size=$(wc -c < "$f")
  entry=$(head -5 "$f" | grep -oE "EXECUTION_STARTED|BATCH_APEX|CRON_|CODE_UNIT_STARTED[^|]*\|[^|]*" | head -1)
  echo "$start  size=$size  $f  entry=$entry"
done | sort

Classify each log by shape:

Step 2: build the timeline

python3 << 'EOF'
import re, os
logs = []
for f in sorted(os.listdir('.')):
    if f.endswith('.log'):
        with open(f) as fp:
            fp.readline()
            m = re.match(r'(\d{2}:\d{2}:\d{2}\.\d+)', fp.readline())
            if m: logs.append((m.group(1), f, os.path.getsize(f)))
logs.sort()
prev = None
for t, f, s in logs:
    delta = ""
    if prev:
        def sec(x):
            h,m,s = x.split(':'); return int(h)*3600+int(m)*60+float(s)
        delta = f"+{sec(t)-sec(prev):.1f}s"
    tp = "small" if s < 1_000_000 else "large"
    print(f"{t}  {tp:5s}  {s:>10}  {f}  {delta}")
    prev = t
EOF

Patterns in deltas:

• Fixed interval every 10 to 60 seconds: scheduled job or retry loop
• Fixed interval every few minutes: scheduled flow or cron
• Tight parent/child pairs within 1 to 5 seconds: single logical operation
• Burst then quiet: bulk load or data migration
• Steadily shrinking intervals: runaway recursion

Step 3: classify the question

Based on what the user is asking, match to the primary investigation category below. The reference file for each category is named in the right column.

If the question touches multiple categories (common), load multiple references.

Step 4: universal patterns worth knowing before opening any reference

Track field value transitions (flip-flop diagnostics)

import re
for f in sorted_logs:
    with open(f) as fp: content = fp.read()
    matches = re.findall(r'RECORD_ID_FRAGMENT[^}]*?FIELD_NAME[=:]"?([^,"}]+)"?', content)
    prev = None
    for i, m in enumerate(matches):
        if m != prev:
            print(f"{f} [{i:3d}] {m}")
            prev = m

Only print transitions. The transition index reveals how deep in the cascade the flip happens. Consistent index across logs = same automation responsible.

Extract the full execution cascade

# Every code unit and flow interview that fired, in order
grep -E "CODE_UNIT_STARTED|FLOW_START_INTERVIEW_BEGIN|BATCH_APEX|VF_APEX_CALL" log.log | head -60

Extract all DML operations

grep -E "DML_BEGIN|DML_END" log.log | head -50

Extract all exceptions

grep -E "EXCEPTION_THROWN|FATAL_ERROR|FLOW_ELEMENT_FAULT|VALIDATION_FAIL" log.log

Identify the running user and context

Every log has a header with the user ID, organization, and trace flag levels. Check:

head -20 log.log | grep -E "USER_INFO|EXECUTION_STARTED|APEX_CODE"

Also check LastModifiedById in any FLOW_VALUE_ASSIGNMENT record dumps. If it points to an integration user (0050B..., 005...), you are looking at automation context. If it points to a human user (005...), it's a UI or API action by that person.

Step 5: identify who wrote a field (the four mechanisms)

A field can change through exactly four mechanisms. Each has a different log signature. Before accusing any specific automation, classify which mechanism is in play:

1. Direct Apex assignment: VARIABLE_ASSIGNMENT target inside a Trigger or Apex class CODE_UNIT_STARTED block. Grep: grep -B2 "FIELD_NAME =" log.log
2. Flow assignment: FLOW_ASSIGNMENT_DETAIL|<flow-id>|<variable>|<value> or the field in FLOW_VALUE_ASSIGNMENT as a changed value. Grep: grep "FLOW_ASSIGNMENT_DETAIL" log.log | grep FIELD_NAME
3. Rollup recalculation (DLRS, native roll-up summary, Apex rollup): field appears in before/after record snapshots with a different value, but nothing targets it in any assignment event. Before-update triggers or master-detail rollups recalculated it.
4. Formula or calculated field: never actually stored. Recalculated on every read. If grep finds it in SELECT queries but never as an assignment target, it is a formula. You cannot trace who "changed" it because nothing writes to it.

Before blaming a flow or trigger, determine which mechanism applies. Check the field metadata if you can: rollups have SummaryField__c markers, formulas have Formula__c markers in record dumps.

Step 6: report with structure

When reporting to the user, always use this structure:

1. Headline: one sentence naming the root cause.
2. Evidence: specific log events (with timestamps or line numbers) that support it.
3. Timeline: if multi-log, the ordered timeline with deltas.
4. Mechanism: how this causes the symptom, in terms of SF platform behavior.
5. What the log cannot tell you: explicit limits on what the log shows.
6. Recommendations: ordered from "stop the bleeding" to "long-term fix".

Do not dump raw log content. Summarize and quote only specific lines that matter.

Limits: be explicit about what the log cannot tell you

The log cannot tell you:

• Which specific record is blocking a merge when the error says not accessible: []
• Why a user's profile/role hierarchy denies access (only that it does)
• What a formula field was "before" the transaction (formulas recalculate, they do not store)
• What happened in a different transaction that is not uploaded
• The org's OWD, sharing rules, role hierarchy, or permission set assignments
• Whether a field is a rollup, a formula, or a direct write (you must check metadata)
• Why a scheduled job fires at a particular time (check Setup > Scheduled Jobs)
• What ran inside a managed package below ENTERING_MANAGED_PKG (by design)
• The content of encrypted fields (shown as **** or omitted)
• What happened on the server between a callout request and response if the remote system is third-party

When hitting one of these, state so plainly. Give the user the concrete next step outside the log: impersonate user X, query child records as admin vs integration user, open the field setup page, check Setup > Monitoring > Apex Jobs, etc.

Reference files

The references/ folder has dedicated guides. Load the ones relevant to the category you identified in step 3:

• event-types.md: complete catalog of APEX_CODE event types, header parsing, log level categories, grep cheat sheet
• flows.md: all flow types (record-triggered, screen, scheduled, platform event, orchestrator), flow events, fault paths, Pause, subflows, bulkification, recursion
• apex-and-async.md: triggers, classes, batch, queueable, future, scheduled, platform events, CDC, test execution, recursion control, mixed DML
• ui-frameworks.md: LWC @AuraEnabled patterns, Lightning Data Service, Aura server actions, Visualforce controllers, Experience Cloud/Communities, OmniStudio
• managed-packages.md: 50+ package signatures with namespace, field patterns, and known gotchas (TracRTC, DLRS, EDA, traa, CPQ, Vlocity, nCino, FinServ, Pardot, Marketo, DocuSign, and many more)
• error-codes.md: DML status codes, flow fault errors, limit exceptions, sharing/access errors, concurrency errors, mixed DML
• governor-and-performance.md: all governor limits, per-namespace tracking, CPU and heap analysis, SOQL selectivity, query plan reading, performance optimization patterns
• legacy-automation.md: workflow rules, process builder (now flow), approval processes, assignment rules, auto-response, escalation, entitlement, time-based actions, order of execution
• integration.md: callouts, named credentials, external services, platform events as integration, CDC, outbound messaging, streaming API, OAuth, Bulk API, MuleSoft/Boomi, Salesforce Connect
• security-sharing.md: OWD, role hierarchy, sharing rules, manual sharing, Apex managed sharing (__Share), implicit sharing, territory management, restriction rules, profile vs permission set, FLS, CRUD, with/without sharing, USER_MODE/SYSTEM_MODE and the apiVersion 67.0 default-user-mode change, the removal of WITH SECURITY_ENFORCED at 67.0, Shield Platform Encryption, Guest User, Community/Experience Cloud access
• specialized-topics.md: Platform Cache, Transaction Finalizers, Continuations, Big Objects, Custom Metadata, Custom Settings, Duplicate Rules, Matching Rules, Lead Conversion, Case Merge, Omni-Channel, Einstein Bots, Einstein Next Best Action, Einstein Activity Capture, Lightning Message Service, Salesforce Functions (deprecated), Heroku Connect, Data Cloud/CDP, Slack integration, Approval Processes, Account/Opportunity/Case Teams, Record Types, Person Accounts, S2S, mobile, and more
• recipes.md: end-to-end investigation workflows for the most common problems: flip-flop field, merge failure, governor limit, UNABLE_TO_LOCK_ROW concurrency, performance bottleneck, recursion/infinite loop, missing field update, user access issue, async job stuck, integration silently failing, bulk upload failing, emergency "stop the bleeding" checklist
• examples.md, gotchas.md, well-architected.md, llm-anti-patterns.md: repo-standard quality-gate files (worked examples, platform gotchas, pillar framing, anti-patterns to avoid).

Read these only when they apply. Do not preload all of them.

Related skills

• apex/debug-and-logging — production logging strategy, structured sinks, async job monitoring (how to instrument).
• apex/debug-logs-and-developer-console — trace flag setup, Developer Console, anonymous Apex, Apex Replay Debugger (how to capture).
• apex/governor-limits and apex/apex-limits-monitoring — deeper governor-limit treatment once a hit is diagnosed.
• apex/common-apex-runtime-errors — error taxonomy reference once a specific exception is identified.

Official Sources Used

• Apex Developer Guide — Debug Log, Debug Log Levels, Event Types
• Apex Reference Guide — System.Limits, AsyncApexJob
• Salesforce Developer Guide — Order of Execution, Governor Limits
• Flow runtime — Flow Fault Paths, Debug a Flow
• Salesforce Help — Monitor Debug Logs, Trace Flags, Apex Replay Debugger
• Salesforce Architects — Well-Architected framework