> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing/issue-tracing/trace-results.md).

# Trace Results

View trace results with visual presentations and debug log visualizers.

When Pharos captures a debug log that matches your trace schedule criteria, it creates a Trace Result record containing the parsed log and analysis tools for investigation.

## Overview

Trace results provide:

* **The captured debug log** - Full Salesforce debug log content
* **Contextual logs** - Surrounding logs before and after the error
* **Highlighted error location** - Pharos automatically identifies where the error occurred
* **Visual debuggers** - Apex debugger and flow debugger (where applicable)
* **Download option** - Export raw log for analysis in external tools

## Anatomy of a Trace Result

### Result Components

Each trace result is made up of three parts: the primary log, its surrounding context logs, and execution details.

**1. Primary Log**

* The debug log where Pharos found the matching error message
* Highlighted to show exactly where the error was detected
* Full execution trace available

**2. Surrounding Logs**

* Additional logs captured before and after the primary log
* Provides context about what led to the error
* Number of surrounding logs controlled by "Captured Trace Log Window" setting

**3. Execution Details**

* User who triggered the error
* Timestamp
* Duration
* Entry point (class/method or flow)

## Captured Log Window

### How It Works

Pharos doesn't just capture the single debug log where the error occurred—it captures logs **before and after** to provide context:

**Example:**

```
Setting: Captured Trace Log Window = 5 (default)

Pharos captures:
  - ~2 logs before the error
  - The log containing the error (highlighted)
  - ~2 logs after the error
  
Total: 5 logs in the trace result
```

### Configuration

The captured log window is configurable, letting you balance how much context you keep against storage usage.

**Location:** Pharos Admin → Tracing Settings

**Setting:** "Captured Trace Log Window"

**Typical Values:**

* **5:** Default, minimal context, smallest storage footprint
* **10-20:** More context, good balance for tricky issues
* **50:** Extended context for complex scenarios

**Calculation:**

* Pharos aims to center the error log in the window
* Roughly half the logs before, half after
* Actual count may vary based on log availability

### Why Surrounding Logs Matter

A single log rarely tells the whole story—surrounding logs reveal what triggered the error and what happened afterward.

**Scenario: Flow Error**

```
Without Context (single log):
  - See that a flow failed
  - Don't know what triggered the flow
  - Don't know what happened before/after
  
With Context (20-log window):
  Log 1-5: Record update that triggered the flow
  Log 6-9: Flow initialization and early steps
  Log 10: ERROR - Flow failed at "Update Records" element
  Log 11-15: Error handling and rollback
  Log 16-20: Subsequent transactions affected by the failure
```

**Value:**

* Understand the **trigger** (what caused the error)
* See the **execution path** (steps leading to error)
* Observe **side effects** (what happened after)

## Viewing Trace Results

### From an Issue

**Issue Detail Page → Tracing Tab → Trace Results**

1. Navigate to the issue
2. Open the **Tracing** tab
3. Find the trace schedule
4. Click to view associated trace results
5. Select a specific result to open

### Result Display

When you open a trace result, you'll see:

**Log List (Left or Top Panel):**

* All captured logs in chronological order
* **Highlighted row:** The log containing the error
* Click any log to view its contents

**Log Details (Right or Bottom Panel):**

* Full debug log contents for selected log
* Syntax highlighting
* Search within log
* Navigation controls

**Selected Log Indication:**

```
Log List:
  [Log 1] 10:15:23 - RecordTrigger.beforeUpdate
  [Log 2] 10:15:24 - FlowExecution.start
  [Log 3] 10:15:25 - FlowExecution.element >>> HIGHLIGHTED (error found here)
  [Log 4] 10:15:26 - FlowExecution.error
  [Log 5] 10:15:27 - RecordTrigger.afterUpdate
```

Pharos automatically highlights Log 3 as the primary result containing the matching error pattern.

## Refresh Behavior

### Auto-Refresh During Active Traces

If you have a trace result open while the trace schedule is still active:

**Behavior:**

* Refreshing the page may cause the selected log to change
* The system selects the log that contains the error (typically the 3rd log or middle of the window)
* This is expected behavior as new logs are captured

**Recommendation:**

* Wait until the trace schedule completes
* Or manually deactivate the schedule before deep analysis
* This ensures the log set remains stable

## Debug Visualizers

Pharos includes built-in debuggers to help analyze captured logs:

### Apex Debugger

The Apex debugger helps you work through logs that contain Apex execution.

**When Available:** For logs containing Apex execution

**Features:**

* Method call hierarchy
* Variable inspection (where logged)
* Stack trace visualization
* Governor limit consumption tracking

**Status:**

* Currently available but still being refined
* Usability improvements planned
* Functional for most debugging scenarios

### Flow Debugger

The Flow debugger visualizes how a flow executed, making it easier to see which element failed.

**When Available:** For logs containing flow execution

**Features:**

* Flow element execution path
* Element-by-element timeline
* Variable values at each step
* Decision outcomes

**Status:**

* Available and functional
* Visual representation of flow execution
* Helps identify which flow element failed

{% hint style="info" %}
**Debugger Refinement**

The Apex and Flow debuggers are usable but still being improved for better user experience. For complex analysis, you may prefer to download the raw log and use external tools.
{% endhint %}

## Downloading Logs

### Why Download?

You may want to download the raw debug log for:

* **External analysis tools:** Chrome plugins, VS Code extensions, Salesforce IDE
* **Deeper analysis:** Advanced parsing and filtering
* **Sharing:** Send to team members or support
* **Archival:** Keep local copy for future reference

### How to Download

**From Trace Result:**

1. Open the trace result
2. Find the **Download** button or option
3. Select the specific log to download (or download all)
4. Save the `.log` file locally

**File Format:**

* Standard Salesforce debug log format (`.log`)
* Compatible with all Salesforce log analysis tools
* Plain text, searchable in any text editor

### External Tools for Log Analysis

Several third-party tools work well with downloaded Salesforce debug logs.

**Popular Options:**

* **Chrome Extensions:** Apex Log Analyzer, Debug Log Analysis
* **VS Code Extensions:** Salesforce Extension Pack (Apex Replay Debugger)
* **Salesforce IDE:** Developer Console (limited), VS Code
* **Text Editors:** Sublime, VS Code (with syntax highlighting)

## Analysis Workflow

### Step 1: Review Highlighted Error Log

1. Open the trace result
2. Identify the highlighted log (where Pharos found the error)
3. Read the error message and immediate context

### Step 2: Check Surrounding Context

1. Look at logs before the error
   * What triggered this execution?
   * What data was being processed?
2. Look at logs after the error
   * How did the system respond?
   * Were there cascading failures?

### Step 3: Use Visual Debuggers

**For Apex Errors:**

1. Open Apex debugger
2. Review method call stack
3. Identify failing line of code
4. Check variable values (if logged)
5. Note governor limit consumption

**For Flow Errors:**

1. Open Flow debugger
2. Review execution path
3. Identify failing flow element
4. Check variable values at each step
5. Understand decision outcomes

### Step 4: Download for Deep Analysis (If Needed)

If the issue is complex:

1. Download the primary log
2. Open in your preferred tool (VS Code, Chrome plugin, etc.)
3. Use advanced search and filtering
4. Correlate with other system logs or data

### Step 5: Document Findings

1. Return to the Pharos issue
2. Add comments documenting:
   * Root cause identified
   * Relevant log lines or execution steps
   * Proposed fix
3. Link to trace result for reference

## Integration with Issue Resolution

Trace results feed directly into the issue resolution workflow:

```mermaid
graph TD
    A[1. Issue Created]
    B[2. Trace Schedule Created - if debug log needed]
    C[3. Trace Result Captured - debug log found]
    D[4. Analysis - using trace result]
    E[5. Root Cause Identified]
    F[6. Fix Implemented]
    G[7. Issue Marked Resolved]
    H[8. Trace Schedule Stopped - if still active]
    A --> B --> C --> D --> E --> F --> G --> H
```

**Trace results provide the crucial data** needed to move from "we know there's a problem" to "we know exactly what's causing it."

## Notifications

When a trace result is captured, Pharos can notify you:

**Notification Configuration:**

* Set up in Pharos Admin → Notifications
* Choose channel (Slack, Teams, Email, PagerDuty)
* Customize message template
* Include link to trace result

**Notification Content:**

Slack and Teams (shared default):

```
Subject: New Trace Result available for Issue ISS-00042 : Apex Exception in OpportunityTriggerHandler

Access the Trace Result here: https://mydomain.my.salesforce.com/a0X...
Category: Apex
Functional Area: Sales
```

Email (dedicated default):

```
Subject: New Trace Result for Issue ISS-00042: Apex Exception in OpportunityTriggerHandler

A new trace result is available for Issue ISS-00042.
Trace Result: https://mydomain.my.salesforce.com/a0X...
Issue: https://mydomain.my.salesforce.com/a0Y...
Category: Apex
Functional Area: Sales
Trace window: 2026-09-16 09:00:00 to 2026-09-16 17:00:00
```

Both email links arrive as clickable anchors. Trace window times are GMT.

**Benefits:**

* Immediate awareness when log is captured
* No need to constantly check for results
* Team can coordinate on analysis
* Faster response to critical issues

## Storage and Retention

### Storage Considerations

Debug logs are large:

* **Typical size:** 100 KB - 10 MB per log
* **Trace result:** 10-20 logs = 1-200 MB per result
* **Multiple results:** Can quickly consume storage

### Retention Policies

Because trace results consume significant storage, set retention policies that purge them once an issue is resolved.

**Recommended Settings:**

```
Pharos Admin → Data Management → Trace Results Retention:

Development/Sandbox: 7 days
Staging: 14 days
Production: 30 days
```

**Reasoning:**

* Debug logs are needed during active debugging
* Once issue is resolved, logs are rarely referenced again
* Aggressive retention prevents storage bloat

### Manual Cleanup

You can also manually delete trace results:

1. Navigate to the trace result
2. Click "Delete"
3. Confirm deletion
4. Logs are permanently removed

**When to Manually Delete:**

* Issue resolved and logs no longer needed
* Captured wrong logs (need to re-trace)
* Storage capacity concerns

## Troubleshooting

### No Trace Results Captured

**Possible Causes:**

1. **Error hasn't occurred yet:** Wait longer or extend trace window
2. **Error pattern mismatch:** Debug log doesn't contain exact error text
3. **Wrong users traced:** Error happening to users not included in schedule
4. **Trace flag limit reached:** Subject to Salesforce's trace-flag limits per org

**Solutions:**

* Verify trace schedule is active
* Broaden error pattern matching
* Expand user targeting
* Check trace flag usage in Salesforce Setup

### Can't View Debug Log Contents

**Possible Cause:** Log file too large for browser

**Solution:**

* Download the log instead
* Analyze in external tool (VS Code, Chrome plugin)
* Contact support if logs consistently can't render

### Trace Result Shows Wrong Log Highlighted

**Possible Cause:** Multiple errors in the captured window

**Solution:**

* Review all logs in the result
* The highlighted log is Pharos's best guess
* Actual error may be in a different log
* Use search functionality to find error message

## Best Practices

### 1. Review Results Promptly

Don't let trace results accumulate:

* Analyze as soon as notification received
* Document findings on the issue
* Stop trace schedule if enough data captured

### 2. Use Visual Debuggers First

Before downloading:

* Try built-in Apex/Flow debuggers
* Sufficient for 80% of debugging scenarios
* Faster than external tool workflow

### 3. Download for Complex Analysis

Download when:

* Issue involves multiple integration points
* Need to correlate with external system logs
* Require advanced filtering/searching
* Debugger isn't providing enough detail

### 4. Clean Up After Resolution

When issue is resolved:

* Review trace results one final time
* Document root cause on issue
* Delete trace results to save storage
* Stop any active trace schedules

## Next Steps

* Learn about [Trace Schedules](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing/issue-tracing/trace-schedules.md) to configure tracing
* Review [Tracing Overview](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing.md) for broader context
* Explore [AI Analysis](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ai-analysis.md) for automated log analysis
