> 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/configuration-guide/tracing.md).

# Tracing

Configure tracing to automatically capture Salesforce debug logs for issues — eliminating the manual trace flag cycle.

Tracing automates the capture of Salesforce debug logs for issues. Instead of manually creating trace flags in Setup, hunting for logs, analyzing them, and repeating the cycle, you create a trace schedule directly from an issue. Pharos sets trace flags during your scheduled windows, monitors for the error, and fetches the relevant debug logs when it occurs.

{% hint style="info" %}
For tracing concepts, workflows, and trace result details, see [Tracing](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing.md).
{% endhint %}

***

## Tracing Settings

**Navigate:** Pharos App → **Pharos Admin** → **Tracing**

![Tracing Settings — disabled state](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-32b04d4e217ae2a66eedab16458ccf7051f7258c%2Ftracing-settings-disabled.png?alt=media)

### Dynamic Tracing

Turn **Enable Dynamic Tracing** on to activate the tracing capability.

![Tracing Settings — enabled with Captured Trace Log Window and Predictive Tracing](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-2bd78c5fd33dfcee12ea2de080c13cefb8f44c2f%2Ftracing-settings-enabled.png?alt=media)

**Captured Trace Log Window** controls how many debug logs Pharos fetches per Trace Result. When a matching error is found in a debug log, Pharos captures not just that log but a window of logs before and after it, providing execution context.

* Default: **5** (total debug logs per Trace Result)
* Set to **20** to get roughly 10 logs before and 10 after the matched error
* The matched log is highlighted in the Trace Result so you know exactly where to look

### Predictive Tracing

Turn **Enable Predictive Tracing** on to unlock the **Auto Trace** capability on trace schedules.

Predictive Tracing uses mathematical modeling to analyze past occurrence patterns and predict the most likely time windows for the error to recur in the coming week. The more historical data available, the more accurate the predictions:

* **Dense data** (many occurrences over weeks) — predictions are distributed across multiple days and time slots
* **Sparse data** (few occurrences) — the model may return a single day's prediction

***

## Creating a Trace Schedule

Trace schedules are created **from the Issue**, not from the admin page. This keeps the trace context tied to the specific problem.

{% stepper %}
{% step %}

### Open the Issue

Navigate to the Issue you want to trace and scroll to the **Trace Schedule** tab at the bottom of the record.
{% endstep %}

{% step %}

### Review Past Occurrences

The calendar view shows a weekly layout. **Red lines** overlaid on the calendar represent past occurrences of this issue — these are your guide for scheduling trace windows.

![Trace Schedule calendar — red lines showing past occurrences on Monday](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-c58e2d05ce0a4be5e17dae776ddaaa7b71771a30%2Fcalendar-occurrences.png?alt=media)

Use the **Occurrences for the last** dropdown to adjust the lookback period:

![Occurrences lookback dropdown — 1 Week, 2 Weeks, 1 Month, 3 Months](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-4d4e4601d64dd800414791935e9beee01187185b%2Foccurrences-dropdown.png?alt=media)

A wider window (1 Month, 3 Months) gives you more data points to identify patterns. The default of 2 Weeks is usually a good starting point.
{% endstep %}

{% step %}

### Create Trace Windows

Click **+ New** to create a trace window:

![New trace window form — User, From, To, Repeat](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-2fa1d4f71cde948dd75dc49adaa2fad7d1e1cf8f%2Ftrace-window-new.png?alt=media)

| Field         | Purpose                                                                                 |
| ------------- | --------------------------------------------------------------------------------------- |
| **User**      | The Salesforce user to trace — Pharos sets a trace flag for this user during the window |
| **From / To** | Date and time range when the trace flag is active                                       |
| **Repeat**    | One-time or recurring window                                                            |

{% hint style="info" %}
Only users impacted by this issue appear in the User dropdown. User-based tracing is the most reliable method — Apex class tracing can be unreliable due to Salesforce platform limitations.
{% endhint %}
{% endstep %}

{% step %}

### Configure Recurrence (Optional)

If the error occurs on a predictable schedule, set the trace window to repeat:

![Repeat options — Do not repeat or Repeat](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-3fd68cff000c02747c0b8bdf1a73cacb20254c10%2Ftrace-window-repeat-options.png?alt=media)

Selecting **Repeat** opens the recurrence configuration:

![Recurrence settings — frequency, days of week, end condition](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-7f4facff1a9b6ac1afb64aa2fcc1a74c8c62a221%2Ftrace-window-recurrence.png?alt=media)

| Setting          | Options                                          |
| ---------------- | ------------------------------------------------ |
| **Repeat every** | N Day / Week / Month                             |
| **Repeat on**    | Day-of-week checkboxes (Sunday through Saturday) |
| **Ends: On**     | Specific date                                    |
| **Ends: After**  | Number of occurrences                            |
| {% endstep %}    |                                                  |
| {% endstepper %} |                                                  |

### The Result

Once created, trace windows appear as purple blocks on the calendar alongside the red occurrence lines:

![Trace schedule — purple trace windows aligned with red occurrence patterns](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-dd19504ff753f50fd58533f7c6c323ca3eab96ac%2Fcalendar-trace-windows.png?alt=media)

![Full trace schedule calendar with user sidebar, controls, and scheduled windows](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-99cc007089fe821ef2c45fd32fdb990120f13f49%2Ftrace-schedule-calendar.png?alt=media)

The left sidebar shows the users being traced (with checkboxes to show/hide their windows). The toolbar provides:

| Control           | Purpose                                                                               |
| ----------------- | ------------------------------------------------------------------------------------- |
| **+ New**         | Create a new trace window                                                             |
| **Auto Trace**    | Use Predictive Tracing to automatically generate windows based on occurrence patterns |
| **Deactivate**    | Deactivate the entire trace schedule                                                  |
| **Today**         | Jump to the current week                                                              |
| **Week** dropdown | Change calendar view                                                                  |

### Editing a Trace Window

Click any existing trace window to edit or delete it:

![Editing trace window TR-0000102 — Integration User, time range, and delete option](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-cbb6c2f0da0eb8550d3c79442f6bb70131d526f3%2Ftrace-window-edit.png?alt=media)

***

## Auto Trace (Predictive)

When Predictive Tracing is enabled in admin settings, the **Auto Trace** button appears on the trace schedule. Clicking it analyzes the issue's occurrence history and automatically creates trace windows for the upcoming week, aligned to the times when the error is statistically most likely to recur.

This is the fastest way to set up a trace — especially for errors with clear time-of-day or day-of-week patterns (e.g., integration jobs that run on a schedule, batch processes that execute nightly).

***

## Reading Trace Results

During each active window Pharos sets a trace flag for the selected user, watches the debug logs for the issue's error pattern, and captures the surrounding window of logs when it finds a match — producing a **Trace Result** record with the matched log highlighted. Navigate to one from the **Trace Results** tab in the Pharos app, or follow a notification link.

{% hint style="info" %}
For the mechanism in full and the analysis workflow, see [Trace Results](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing/issue-tracing/trace-results.md). You can also configure [notification rules](https://docs.pharos.ai/configuration-guide/notifications/trace-results.md) on Trace Results to be alerted when a debug log is captured.
{% endhint %}

### Header and Metadata

The top of every trace result shows the key context at a glance:

![Trace Result TR-0000001 — header with linked issue, trace schedule, date range, and created-by user](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-f2cfd9b4d8820908150c734b2f65714edc91237c%2Ftrace-result-overview.png?alt=media)

| Field                      | Purpose                                                                            |
| -------------------------- | ---------------------------------------------------------------------------------- |
| **Issue**                  | The issue this trace was initiated from (e.g., ISS-00002) — click to navigate back |
| **Trace Schedule**         | The schedule that produced this result (e.g., ISS-00002)                           |
| **Trace Start / End Date** | The time window during which the trace flag was active                             |
| **Created By**             | The user whose scheduled job captured the result, with a timestamp                 |

### Debug Logs Table

Below the header is the **Debug Logs** table — a list of Salesforce debug logs captured in this trace result.

| Column          | Description                                                                      |
| --------------- | -------------------------------------------------------------------------------- |
| **User**        | The Salesforce user ID whose execution generated the log                         |
| **Application** | Browser, Unknown, etc. — the Salesforce application context                      |
| **Request**     | Application, Api — the type of request that generated the log                    |
| **Operation**   | The entry-point operation (e.g., `/aura`, `FutureHandler`, `EmailToApexHandler`) |
| **Status**      | Success or the error encountered (e.g., "Divide by 0")                           |
| **Duration**    | Execution time in milliseconds                                                   |
| **LogSize**     | Size of the raw debug log in bytes                                               |
| **StartTime**   | When the execution began                                                         |
| **Download**    | Download icon to export the raw `.log` file                                      |

#### How the Row Count Relates to the Captured Trace Log Window

The number of rows in this table is controlled by the **Captured Trace Log Window** setting in Pharos Admin → Tracing. When Pharos detects the error in a debug log, it doesn't just fetch that one log — it grabs a window of logs around it:

* **Default (5):** Pharos captures roughly 5 debug logs total — a couple before the matched error, the matched log itself, and a couple after
* **Set to 20:** You get approximately 10 logs before and 10 logs after the error, for 20 rows total
* **Higher values** give broader context but consume more storage

The matched log — the one containing the actual error — is **highlighted** in the table (shown with a colored row) so you can immediately see which log to focus on. In the screenshot above, the second row shows a "Divide by 0" status, indicating that this is the log where Pharos found the error pattern from the issue.

{% hint style="warning" %}
Each debug log in the table is a separate Salesforce execution — not individual lines within a single log. A trace result with 10 rows means Pharos fetched 10 complete debug logs from that time window. Large log windows consume more org storage.
{% endhint %}

### Tree View

Click any row in the Debug Logs table to load its contents. The **Tree** tab (selected by default) displays the raw debug log as a hierarchical execution tree.

![Tree view — execution tree showing HEAP\_ALLOCATE, VARIABLE\_SCOPE\_BEGIN, and CODE\_UNIT entries](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-615284f8417521fbf4965a661a0bf13bfb80c2ce%2Ftrace-result-tree-view.png?alt=media)

The tree mirrors the structure of a standard Salesforce debug log, with nested events showing the call hierarchy:

* **EXECUTION\_STARTED** → the outermost execution boundary
* **CODE\_UNIT\_STARTED** → Apex class or trigger entry points
* **METHOD\_ENTRY / METHOD\_EXIT** → individual method calls
* **VARIABLE\_SCOPE\_BEGIN** → variable assignments and their values
* **HEAP\_ALLOCATE** → memory allocations

Use the **Search** box to find specific events, classes, or variable names within the tree. The **Finest** dropdown controls the log level filter — set it to **Finest** to see all events, or filter to a higher level to reduce noise.

Click the expand icon (top-right of the tree panel) to open the tree in a full-screen view for easier navigation of large logs.

![Full-screen tree view — expanded log with variable assignments and heap allocations](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-13d754bc9a1eade13b399b5f7d2ae0714e001b04%2Ftrace-result-tree-fullscreen.png?alt=media)

### Chart View

The **Chart** tab provides a visual timeline of the debug log execution.

![Chart view — timeline visualization with colored execution bars and call hierarchy](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-274a3c6037f538f1b79566feaf7b0f3aa93b06e4%2Ftrace-result-chart-view.png?alt=media)

The chart has two parts:

**Top timeline** — a minimap showing the entire execution duration. Colored bars represent different execution contexts (Apex, system methods, DML, etc.). Use this to identify where time is being spent at a glance.

**Bottom detail view** — an expanded section with a hierarchical breakdown on the left (ROOT → EXECUTION\_STARTED → CODE\_UNIT\_STARTED → METHOD\_ENTRY, etc.) and corresponding time bars on the right. This lets you see exactly how long each method or operation took relative to the overall execution.

![Full-screen chart — detailed timeline with method-level execution bars](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-489162431cb53671407fe4eab810dad16c8b2a99%2Ftrace-result-chart-fullscreen.png?alt=media)

The chart view is particularly useful for:

* Identifying **performance bottlenecks** — long bars indicate slow operations
* Understanding **execution order** — see exactly what ran and when
* Spotting **unexpected callouts or DML** — visual patterns that stand out in the timeline

### Debug View

The **Debug** tab provides a step-through debugger for Apex execution. Use the arrow buttons at the top to step forward and backward through the execution, watching variables change in the right-hand panel as you go.

{% hint style="info" %}
The Apex and Flow debuggers are functional but still being refined. For complex analysis, you can always download the raw log and use external tools like VS Code's Apex Replay Debugger or a Chrome-based log analyzer.
{% endhint %}

### Downloading Logs

Each row in the Debug Logs table has a **download icon** on the right. Click it to export the raw Salesforce debug log as a `.log` file. This is useful when:

* The built-in viewers don't provide enough detail for your scenario
* You want to use the **Apex Replay Debugger** in VS Code
* You need to share the log with a developer or Salesforce support
* You prefer a Chrome plugin or other external log analysis tool

***

## Limits and Constraints

Schedule lifecycle — one active schedule per issue, and automatic deactivation once no active windows remain — is covered in [Trace Schedules](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing/issue-tracing/trace-schedules.md). The platform constraints to plan around when configuring:

* **Trace Results consume storage** — Salesforce generates debug logs during trace windows, which count toward org storage. Be frugal with trace windows and deactivate schedules when you have what you need
* **50 concurrent trace flags per org** — a Salesforce platform maximum. If you're tracing many issues simultaneously, you may hit this limit
* **25 MB debug log truncation** — Salesforce truncates debug logs larger than 25 MB, so a very large execution may produce an incomplete captured log

***

## Troubleshooting

| Issue                                   | Cause                                | Resolution                                                                          |
| --------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------- |
| No trace schedule tab on the issue      | Dynamic Tracing not enabled          | Enable in Pharos Admin → Tracing                                                    |
| No users available in the dropdown      | No users impacted by this issue      | The issue must have recorded at least one affected user                             |
| Auto Trace button not visible           | Predictive Tracing not enabled       | Enable in Pharos Admin → Tracing → Predictive Tracing                               |
| Trace flag limit (50) reached           | Too many concurrent traces           | Deactivate trace schedules on resolved issues                                       |
| No debug log captured                   | Error didn't occur during the window | Extend or add more trace windows; use Auto Trace for better coverage                |
| Debug log incomplete or truncated       | Log exceeds 25 MB                    | Salesforce limitation — narrow the trace window or reduce debug log levels in Setup |
| Predictive Tracing returns a single day | Sparse occurrence data               | Allow more time for data to accumulate, or widen the Occurrences lookback period    |

***

## Related

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>🎯 Issue Tracing</strong></td><td>Trace schedules, results, and workflows</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing/issue-tracing.md">Issue Tracing</a></td></tr><tr><td><strong>📊 Trace Result Notifications</strong></td><td>Get alerted when debug logs are captured</td><td><a href="https://docs.pharos.ai/configuration-guide/notifications/trace-results.md">Trace Results</a></td></tr><tr><td><strong>🔱 Triton</strong></td><td>Custom instrumentation as an alternative to debug logs</td><td><a href="https://docs.pharos.ai/configuration-guide/advanced/triton.md">Triton</a></td></tr></tbody></table>
