> 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/notifications/trace-results.md).

# Trace Results

Configure trace result notification rules to get alerted when Pharos captures a debug log from a trace schedule.

Trace result notifications alert you when Pharos captures a debug log that matches your trace schedule criteria. Instead of repeatedly checking whether a trace has produced results, you receive a message in Slack, Teams, or Email the moment a result is captured—so your team can begin analysis immediately.

{% hint style="info" %}
For tracing concepts and the debug log capture workflow, see [Tracing](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing.md) and [Trace Results](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing/issue-tracing/trace-results.md).
{% endhint %}

***

## Why Trace Result Notifications?

Tracing is an asynchronous process—you create a trace schedule, define time windows, and wait for the error to occur. Without notifications, you need to manually check the issue's Tracing tab to see if a result has been captured. This is tedious, especially when:

* The error is intermittent and you don't know when it will occur
* Multiple team members are waiting on the trace result
* You have traces running on multiple issues simultaneously

Trace result notifications solve this by pushing the result to your team immediately.

Trace result rules are configured in **Pharos Admin → Notifications → Trace Results**.

![Trace Results tab — notification rules for debug log captures from tracing](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-74d2620374fbab2b0e566ae80b4dd81a7f964773%2Fnotifications-trace-results-tab.png?alt=media)

***

## Configuration

{% stepper %}
{% step %}

### Navigate to trace result rules

1. Open **Pharos Admin → Notifications → Trace Results**
2. Click **Add New Rule**
   {% endstep %}

{% step %}

### Name and type

1. Enter a descriptive name (e.g., "Trace result captured → Slack")
2. Set **Rule type** to **Create** (trace result notifications typically use create rules)
   {% endstep %}

{% step %}

### Filter criteria (optional)

For most teams, a single catch-all rule (no filters) works well because trace results are already low-volume — they only fire when a trace schedule captures a matching debug log.

Filter criteria on this tab are **Issue** fields, the same set the Issues tab offers, applied to the Issue the trace result belongs to. The on-screen help text reads "any field on the Issue record" for this reason. Use them to narrow to, say, a single Functional Area or Category.
{% endstep %}

{% step %}

### Notification action

1. Click **Add New** under Notifications
2. Select channel (Slack, Teams, PagerDuty, Email, or Webhook)
3. For Slack, Teams, Email and Webhook, Subject and the message body prefill with that channel's default template — Email gets a dedicated trace result template, Slack and Teams share a shorter one (see [Message Template](#message-template)). A PagerDuty action starts empty
4. Adjust the text if you need extra fields, then click **Add**, then **Save**
   {% endstep %}
   {% endstepper %}

{% hint style="info" %}
Defaults prefill only when you **add a new** action. Editing an action you already saved never overwrites its subject or message body. Changing template text requires the **Rule Template Customization** permission.
{% endhint %}

***

## Message Template

Trace result notifications reference the **Trace Result** object. The **Insert Field** picker shows Trace Result fields, including Issue fields reached through the `Issue__r` relationship. Its **Link** entry is the Trace Result link only — there is no picker entry for the Issue link, so type `{!Trace_Result__c.Issue__c.Link}` by hand if you want one, though the Email default below already includes that line.

Slack, Teams, Email and Webhook prefill a default when you add a new action. Email has a dedicated template; Slack and Teams share a shorter one; Webhook has its own, which this page does not reproduce. PagerDuty has no default template — a new PagerDuty action opens with Subject and Message blank.

{% hint style="info" %}
Merge fields are shown here without a namespace. In a namespaced org the **Insert Field** picker inserts the `pharos__` form (`{!pharos__Trace_Result__c.pharos__Issue__r.pharos__Summary__c}`); both forms resolve, so a template copied from this page works either way.
{% endhint %}

### Email default

**Subject**

```
New Trace Result for Issue {!Trace_Result__c.Issue__r.Name}: {!Trace_Result__c.Issue__r.Summary__c}
```

**Message**

```
A new trace result is available for Issue {!Trace_Result__c.Issue__r.Name}.
Trace Result: {!Trace_Result__c.Link}
Issue: {!Trace_Result__c.Issue__c.Link}
Category: {!Trace_Result__c.Issue__r.Category__c}
Functional Area: {!Trace_Result__c.Issue__r.Functional_Area__c}
Trace window: {!Trace_Result__c.Trace_Start_Date__c} to {!Trace_Result__c.Trace_End_Date__c}
```

In the delivered email both links render as clickable anchors — one to the Trace Result record, one to the related Issue record. The trace window renders as `yyyy-MM-dd HH:mm:ss` in **GMT**, not the recipient's time zone.

### Slack and Teams default

Slack and Teams share a shorter template:

**Subject**

```
New Trace Result available for Issue {!Trace_Result__c.Issue__r.Name} : {!Trace_Result__c.Issue__r.Summary__c}
```

**Body**

```
Access the Trace Result here: {!Trace_Result__c.Link}
Category: {!Trace_Result__c.Issue__r.Category__c}
Functional Area: {!Trace_Result__c.Issue__r.Functional_Area__c}
```

### Customizing

The Email default already carries the link, the Issue context, and the trace window, so most teams save it as-is. Add fields only if your workflow needs them — for example the **Trace Result** name, or the **Trace Schedule** the result came from.

***

## How Trace Results Relate to the Tracing Workflow

Trace result notifications fit into the broader tracing workflow:

```mermaid
graph TD
    A[1. Issue created — error detected]
    B[2. Trace schedule created from the issue]
    C[3. Trace windows active — Pharos sets trace flags]
    D[4. Error occurs during window — debug log captured]
    E[5. Trace Result created]
    F[6. Notification sent — team alerted]
    G[7. Team analyzes trace result — root cause identified]
    A --> B --> C --> D --> E --> F --> G
    style A fill:#bf360c,stroke:#5d4037,color:#fff
    style G fill:#2e7d32,stroke:#1b5e20,color:#fff
```

The notification at step 6 eliminates the need to poll for results. Your team can be doing other work and jump into analysis the moment the notification arrives.

***

## Best Practices

1. **A single catch-all rule is usually enough.** Trace results are inherently low-volume (one per captured debug log), so filtering is rarely necessary. A simple "notify me on every trace result" rule covers most workflows.
2. **Use Slack or Teams, not Email.** Trace results are time-sensitive—you want immediate awareness so the team can coordinate on analysis before the context goes stale.
3. **Include the link.** The most valuable part of a trace result notification is the link that takes you directly to the captured debug log. Make sure the link field is included in the message body.
4. **Coordinate with the tracing team.** If multiple people are waiting on a trace result, send the notification to a shared channel rather than a direct message so everyone sees it.
5. **Review trace results promptly.** Analyze the captured debug log as soon as the notification arrives. Document findings on the issue and stop the trace schedule if you have enough data—this frees up trace flag capacity (Salesforce allows a maximum of 50 trace flags per org).

***

## Practical Example

**Scenario:** A flow error is occurring intermittently for a specific user. You've created a trace schedule from the issue, with trace windows during the user's working hours.

**Setup:**

| Setting       | Value                   |
| ------------- | ----------------------- |
| **Rule name** | Trace result captured   |
| **Rule type** | Create                  |
| **Filters**   | None (catch-all)        |
| **Channel**   | Slack #dev-team         |
| **Subject**   | Default                 |
| **Body**      | Default (includes link) |

**Result:** When the error occurs during a trace window, Pharos captures the debug log, creates a Trace Result, and immediately sends a Slack notification to #dev-team. The developer clicks the link, opens the trace result, uses the [visual debugger](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing/issue-tracing/trace-results.md) to identify the failing flow element, and documents the root cause on the issue.

***

## Troubleshooting

| Issue                                           | Cause                                                                    | Resolution                                                                             |
| ----------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| No notification received                        | No active trace schedule, or error hasn't occurred during a trace window | Verify the trace schedule is active and the trace windows cover the expected timeframe |
| Notification received but trace result is empty | Debug log was captured but didn't contain the expected error             | Check the error pattern configured on the trace schedule; broaden the match criteria   |
| Multiple notifications for the same issue       | Multiple trace results captured in the same window                       | This is expected—each captured debug log creates a separate trace result               |

***

{% hint style="info" %}
**Related:** [Tracing Configuration](https://docs.pharos.ai/configuration-guide/tracing.md) — Configure tracing settings and trace schedules · [Issue Notifications](https://docs.pharos.ai/configuration-guide/notifications/issues.md) — Production notification rules · [Notification Actions](https://docs.pharos.ai/configuration-guide/notifications/notification-actions.md) — Channel configuration · [Trace Results](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing/issue-tracing/trace-results.md) — Conceptual overview of trace results
{% endhint %}
