> 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/logs/log-processing/log-enrichment.md).

# Log Enrichment

Learn what data is added to log records during enrichment and why it's useful.

Log enrichment is the process of automatically adding contextual information to raw log entries, transforming sparse error messages into actionable intelligence. Pharos enriches every log with metadata that would otherwise require manual investigation.

## Overview

Raw Salesforce errors carry little context on their own, so Pharos automatically enriches every log with the surrounding details needed to diagnose the problem.

{% hint style="info" %}
**From Sparse to Rich**

Enrichment transforms a cryptic one-line error message into a complete diagnostic report. This context is what enables developers to fix issues in minutes rather than hours or days.
{% endhint %}

### The Problem with Raw Logs

When Salesforce generates an error, the raw information is often minimal:

**Example Raw Error:**

```
System.NullPointerException: Attempt to de-reference a null object
at OpportunityTriggerHandler.afterUpdate line 156
```

**What's Missing:**

* Which user triggered this error?
* Which records were involved?
* Were there governor limit pressures?
* What other automation was running at the same time?
* What configuration changes happened recently?

Without this context, developers spend hours investigating what should take minutes.

### Pharos's Solution: Automatic Enrichment

Pharos **automatically** captures and attaches contextual metadata to every log entry:

**Same Error, Enriched:**

*System.NullPointerException: Attempt to de-reference a null object at OpportunityTriggerHandler.afterUpdate line 156*

```mermaid
graph TD
    A[Enriched Context]
    A --> U[User: John Doe - Sales Rep profile]
    A --> R[Records Involved]
    R --> R1[Opportunity 006xxx - from the log's Related ID field, link into your org]
    A --> G[Governor Limits]
    G --> G1[SOQL: 47 of 100]
    G --> G2[DML: 12 of 150]
    G --> G3[CPU: 8,456ms of 10,000ms]
    G --> G4[Heap: 4.2MB of 6MB]
    A --> S[Stack Trace]
    S --> S1[OpportunityTriggerHandler.afterUpdate line 156]
    S --> S2[OpportunityTriggerHandler.processClosedWon line 89]
    S --> S3[OpportunityValidator.checkIndustry line 23 - Likely null check missing]
    A --> T[Audit Trail]
    T --> T1[10:10 - Validation Rule Opportunity_Stage_Validation modified]
    A --> E[Environment: Org 00Dxxx - 2026-01-12 10:15:23 PST - Trigger after update]
```

**Result:** The developer sees who hit the error, the governor limits at the moment of failure, the stack trace, and a validation rule change made minutes earlier. Note where the Opportunity ID comes from: it is not in the message text above. The trigger set it as the log's **Related ID** when it logged the error, and enrichment labelled it an Opportunity from its `006` key prefix. One click opens that Opportunity in Salesforce, and following its Account lookup shows Industry is blank—the null the trigger doesn't handle.

## Types of Enrichment

Pharos adds multiple layers of contextual data. Each enrichment type provides specific insights that accelerate troubleshooting and root cause analysis:

| Enrichment Type          | What's Added                                                                          | Primary Value                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **User Context**         | User name, profile, role, licence type; login type, session type and source IP        | Impact assessment, permission debugging                                         |
| **Record Context**       | IDs of records referenced in the log, with their object types                         | See which records were involved and open them in your org                       |
| **Governor Limits**      | SOQL, DML, CPU, Heap usage at failure                                                 | Performance bottleneck identification                                           |
| **Stack Trace**          | Interactive call chain with code context                                              | Precise error location and execution path                                       |
| **Environment**          | Org ID, timestamp, transaction ID, API version                                        | Multi-org tracking, timing correlation                                          |
| **Audit Trail**          | Recent setup changes, deployments, metadata edits                                     | Change correlation, rollback decisions                                          |
| **Flow-Specific**        | Flow diagrams, decision paths, and the values reported in the flow error notification | Visual flow debugging, variable inspection                                      |
| **Integration Payloads** | HTTP request/response, latency, retry attempts                                        | API debugging, external system issues (any log carrying an integration payload) |

## What Enrichment Reads

Enrichment draws on platform data—the `User` behind the log, the session, org limits, recent setup changes, the stack trace text—not on your business records. Two facts are worth holding separately.

**Record involvement, not record contents.** Pharos records *which* records a log referred to. ID-shaped tokens are found by scanning the log's own text (its related ID, summary, and details), and each one is labelled with the object type its three-character key prefix identifies. What is stored is the ID plus that label, rendered as a link into your org. Opening the link loads the record from Salesforce, in your browser, under your own permissions. Pharos does not read the record and does not store its contents.

**Log text carries whatever your org's errors emit.** An exception message, a stack trace, a Flow error notification, or an integration payload can itself contain values, because Salesforce or your own code put them there. Pharos stores that text as it was received. That is exactly why data masking exists, and why it targets those text fields.

Put together: Pharos records which records were involved; the contents of a log are whatever the originating error text already contained.

{% hint style="info" %}
**Where to look next**

[Permissions](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/access-controls/permissions.md) states what Pharos can and cannot access in your org. [Data Masking](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/access-controls/data-masking.md) controls which values are allowed to persist in log text.
{% endhint %}

## Enrichment Types in Detail

### 1. User Context

**What's Captured, from the `User` record behind the log:**

* User ID and Name
* Profile
* Role
* Licence type

**What's Captured, from the login session behind the log (`AuthSession`):**

* Login type and session type
* Source IP address

**Why It Matters:**

* **User impact assessment:** Is this affecting one user or many?
* **Permission debugging:** Does the user's profile or licence type explain the failure?
* **Profile-specific issues:** Errors only affecting certain profiles
* **Access context:** Did the request come from the UI, the API, or an integration user's session?

**Example Use Case:**

```
Error: "Insufficient privileges to update Contact"

Enriched Context:
  User: Jane Smith
  Profile: Partner Community User
  Licence: Partner Community
  Session: API login
  
Insight: External users lack Contact edit permission. 
         Not a bug—working as designed.
```

### 2. Record Context

**What's Captured:**

* The IDs of every record the log referred to, found by scanning the log's related ID, summary, and details for ID-shaped tokens
* The object type behind each ID, derived from its three-character key prefix
* Each ID rendered as a link into the source org

{% hint style="info" %}
Pharos does not read those records: no field values, record names, or owners are retrieved or stored. See [What Enrichment Reads](#what-enrichment-reads).
{% endhint %}

**Why It Matters:**

* **Data-specific issues:** See whether failures cluster on the same records or the same object type
* **Impact assessment:** Count the distinct records an issue touched
* **Quick navigation:** Open every record the log referred to in your org, in one click
* **Relationship debugging:** Open a referenced record to check whether a parent or lookup is empty

**Example Use Case:**

```
Error: "DML Exception: Cannot insert duplicate value"

Enriched Context:
  Records Involved:
    Lead 00Qxxx (link into your org)
    Lead 00Qyyy (link into your org)
  
Insight: Salesforce's duplicate-value error named both Leads, and both IDs
         were scraped from that same error text—neither Lead was read by
         Pharos. Open either link to compare them in Salesforce.
```

On the log itself, this appears as the **Related Objects** panel. IDs are grouped by object type with a count per type—for example *Accounting Variable (3)* listing three IDs and *PO Item Line (1)* listing one—and every ID is a hyperlink into the source org. There are no record names and no field values in the panel, because neither was ever read. A **Download CSV** control exports the list of IDs.

![The Related Objects panel on a log — referenced record IDs grouped by object type with a count per type, Accounting Variable (3) and PO Item Line (1), each ID a hyperlink into the source org, and a Download CSV control in the panel header](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-840f9305c6290a587d25e32e4642c4938eb27705%2Frelated-objects-panel.png?alt=media)

### 3. Governor Limit Context

**What's Captured:**

* SOQL Queries used/limit
* DML Statements used/limit
* CPU Time consumed/limit
* Heap Size used/limit
* Callout count/limit
* Platform Event publishes/limit

**Why It Matters:**

* **Performance bottlenecks:** Identify inefficient queries
* **Limit approaching:** Warnings before hitting hard limits
* **Resource contention:** Multiple processes competing for limits
* **Optimization targets:** Know which limits to optimize

**Example Use Case:**

```
Error: "System.LimitException: Too many SOQL queries: 101"

Enriched Context:
  Governor Limits at failure:
    SOQL Queries: 101 of 100 (EXCEEDED)
    DML Statements: 15 of 150
    CPU Time: 2,345ms of 10,000ms
    
  Stack Trace:
    OpportunityTriggerHandler.afterUpdate (line 156)
    - Called 85 times in trigger context (bulk operation)
    
Insight: SOQL query inside loop. Need to bulkify trigger.
         Move SOQL outside loop, use Map for lookups.
```

### 4. Stack Trace Enhancement

**What's Captured:**

* Full Apex stack trace (class, method, line number)
* Interactive navigation (click to expand)
* Code context (surrounding lines)
* Method signatures and parameters

**Why It Matters:**

* **Precise error location:** Exact line causing failure
* **Call chain visibility:** Understand execution path
* **Quick navigation:** Jump directly to problematic code
* **Context awareness:** See what called what

**Example:**

```
Enhanced Stack Trace:

OpportunityTriggerHandler.afterUpdate (line 156)
  Code Context:
    154:  for (Opportunity opp : newOpps) {
    155:    if (opp.StageName == 'Closed Won') {
>>> 156:      String industry = opp.Account.Industry.toUpperCase();  ← NULL POINTER
    157:      sendNotification(opp);
    158:    }
    
Called by: OpportunityTriggerHandler.handleAfterUpdate (line 42)
Called by: OpportunityTrigger (line 8)
```

### 5. Environment Snapshot

**What's Captured:**

* Org ID and Instance
* Environment Type (Production, Sandbox, Scratch Org)
* Salesforce API Version
* Timestamp (with timezone)
* Transaction ID (if using Triton)
* Request ID (Salesforce internal tracking)

**Why It Matters:**

* **Multi-org visibility:** Track errors across sandboxes and production
* **Timing correlation:** Link errors to deployments or external events
* **Environment-specific issues:** Bugs only in production vs. sandbox
* **Transaction tracing:** Follow multi-step processes end-to-end

### 6. Audit Trail Context

**What's Captured:**

* Recent Setup Audit Trail entries
* Deployment history
* Metadata modifications

**Why It Matters:**

* **Change correlation:** Did a recent deployment cause this?
* **Configuration debugging:** Was a validation rule or workflow recently changed?
* **Rollback decisions:** Should we revert a recent change?
* **Root cause identification:** Link errors to specific configuration changes

**Example Use Case:**

```
Error: 47 Opportunity trigger exceptions starting 10:15 AM today

Enriched Context:
  Audit Trail:
    10:10 AM - Admin Sarah modified Validation Rule "Opportunity_Stage_Validation"
    Change: Added required field check for "Industry" on Closed Won stage
    
Insight: New validation rule causing exceptions in trigger logic 
         that doesn't handle null Industry field.
         
Action: Either revert validation rule or update trigger to handle null.
```

### 7. Flow-Specific Enrichment

**For Flow Errors:**

* Visual flow diagram (interactive, shows path taken)
* The values Salesforce reported in the flow error notification
* Decision branch taken (which path in flow)
* Flow version and API name
* Flow type (Screen Flow, Record-Triggered, Scheduled, etc.)

**Why It Matters:**

```
Traditional Flow Error:
  "Flow failed to access value for FlowVariable: AccountName"
  
Enriched Flow Error:
  Flow: "Lead Conversion Flow" (Version 3)
  Failed Element: "Update Account" (Decision → False Branch)
  Variable Values:
    LeadId: 00Qxxx
    AccountName: NULL ← This is the problem
    ContactId: 003xxx
  Visual Diagram: (shows full flow with failure point highlighted)
  
Insight: AccountName variable not populated. 
         Need to add null check or populate earlier in flow.
```

{% hint style="info" %}
**Where these values come from**

Pharos assembles this from the flow error notification Salesforce sends to its [email service](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-ingestion-methods/automated-error-tracking.md). That notification already contains the resolved variable values; Pharos stores the message it received and structures the per-element results for the diagram. It does not read the flow interview and does not query any record. Where those values can be sensitive, use [data masking](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/access-controls/data-masking.md).
{% endhint %}

### 8. Integration Payload Enrichment

**For logs carrying integration payloads (any category):**

* Request URL and method (GET, POST, etc.)
* Request headers (sanitized)
* Request body (JSON/XML payload)
* Response status code
* Response body
* Response time (latency)
* Retry attempts (if applicable)

**Why It Matters:**

* **API debugging:** See exact request/response
* **Timeout analysis:** Measure external system performance
* **Authentication issues:** Track token expiration
* **Replay capability:** Resubmit failed requests for testing

**Example:**

```
Error: "HTTP 503 Service Unavailable"

Enriched Context:
  Integration: "ERP Order Sync"
  Request:
    URL: https://erp.example.com/api/orders
    Method: POST
    Headers: [Authorization, Content-Type]
    Body: {"orderId":"ORD-123","amount":1250.00}
  Response:
    Status: 503
    Body: "Service temporarily unavailable. Retry after 60 seconds."
    Latency: 10,234ms (timeout at 10,000ms)
  Retry Attempts: 3 (all failed)
  
Insight: External ERP system down. Not a Salesforce issue.
         Check with vendor. Enable retry logic with exponential backoff.
```

## Enrichment Process

Enrichment runs asynchronously after a log is captured, so it adds context without affecting your transaction performance.

### When Does Enrichment Happen?

Enrichment occurs **asynchronously** after the log is captured. This ensures zero impact on your transaction performance:

| Stage                        | What Happens                                                 | Timing      | Impact on Transaction              |
| ---------------------------- | ------------------------------------------------------------ | ----------- | ---------------------------------- |
| **1. Log Capture**           | Pharos captures raw error via automated collection or Triton | Immediate   | None (automated) or <10ms (Triton) |
| **2. Platform Event**        | Log data published as platform event                         | <100ms      | None (async publish)               |
| **3. Background Processing** | Pharos subscriber consumes the event                         | <1 second   | Zero (separate context)            |
| **4. Enrichment**            | Additional metadata queried and attached                     | 1-3 seconds | Zero (async queries)               |
| **5. Persistence**           | Enriched log saved to custom object                          | <500ms      | Zero (async save)                  |
| **6. Availability**          | Log visible in Pharos UI with full context                   | <500ms      | Zero (UI render)                   |

**Total Latency:** Typically **1-5 seconds** from error occurrence to enriched log availability in the Pharos UI.

### Performance Impact

{% hint style="success" %}
**Zero Transaction Impact:** Enrichment happens **asynchronously** via platform events. Your Apex/Flow execution completes immediately, and enrichment happens in the background. Your governor limits remain untouched by the enrichment process.
{% endhint %}

**Common Question:** Does enrichment slow down my transactions?

**Answer:** No. The enrichment queries (platform-object SOQL lookups, metadata API calls) run in a **separate platform event subscriber context** after your transaction completes. They don't consume your transaction's governor limits or CPU time.

**Triton Logging Overhead:** If you manually log with Triton, there's a small CPU/heap cost to publish the platform event, but it's minimal (<10ms typically) and negligible compared to normal business logic execution.

## Enrichment Benefits

Enriched context speeds up troubleshooting, surfaces patterns, and powers prioritization and alerting.

### Faster Troubleshooting

**Without Enrichment:**

```
Time to investigate a single error:
  1. Read error message (2 min)
  2. Find user who reported it (5 min)
  3. Query record involved (3 min)
  4. Check governor limits (manual debug log parsing, 10 min)
  5. Review audit trail (5 min)
  6. Correlate with deployment (10 min)
  
Total: 35 minutes per error
```

**With Enrichment:**

```
Time to investigate:
  1. Open log in Pharos (all context pre-loaded)
  2. Review enriched data
  
Total: 3 minutes per error
```

**Savings:** 90% reduction in investigation time.

### Proactive Error Detection

Enrichment enables **pattern recognition**:

**Example:**

```
Pattern Detected: All errors affecting Partner Community users
  → Insight: Permission set missing for external users
  
Pattern Detected: Errors spike at 2 AM daily
  → Insight: Batch job conflict with scheduled flows
  
Pattern Detected: Every failure references the same Account ID
  → Insight: One record is driving the errors—open it and check its data
```

### Impact-Based Prioritization

Enriched user and record-ID data enables **smart triage**:

```
Issue A:
  Users Impacted: 1 (Internal Admin)
  Records: 3 distinct record IDs
  Priority: Low
  
Issue B:
  Users Impacted: 47 (External Sales Reps)
  Records: 823 distinct Opportunity IDs
  Priority: Highest
```

### Automated Alerting

Enrichment data enables **context-aware notifications**:

```
Notification Rule:
  Trigger: Issue Created
  Condition: User Impact > 10 AND Object Type = "Opportunity"
  Action: Page on-call engineer via PagerDuty
  
Without enrichment: Can't evaluate "User Impact > 10"
With enrichment: Rule evaluates automatically
```

## Enrichment Configuration

Enrichment itself is not configurable. Two adjacent settings shape what persists and for how long.

### What You Can Control

| Configuration                                                                                                                  | Options                                                                                                     | Purpose                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [**Data Masking**](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/access-controls/data-masking.md) | Regex patterns for sensitive data                                                                           | Redact SSNs, credit cards, passwords, PII from logs                                   |
| [**Retention**](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-storage/data-retention.md)      | Any age threshold in days, optionally filtered by log characteristics; remove and/or archive to Big Objects | Define how long enriched logs are kept, and whether they are preserved before removal |

### What's Automatic

Those two settings are the whole of it—there is nothing else to tune. Every enrichment type is always active, and none of them has a depth, scope, or field-selection setting:

* User context (profile, role, licence type, session)
* Governor limits (SOQL, DML, CPU, Heap)
* Stack traces (enhanced with code context)
* Audit trail correlation (recent setup changes)
* Environment snapshot (org ID, timestamp, API version)
* Related record discovery (IDs found in the log text)
* Flow-specific context (diagrams, values reported in the flow error)
* Integration payload details (request/response, latency)

## Best Practices

To get full value from enrichment, lean on the enriched context rather than the raw error message alone.

### 1. Review Enriched Logs, Not Just Error Messages

**Anti-Pattern:**

```
Developer: "Error says null pointer on line 156. Let me check the code."
[Spends 30 minutes adding debug statements and redeploying]
```

**Better Approach:**

```
Developer: "Let me open the enriched log in Pharos."
[Sees the user, the limits, a validation rule changed minutes earlier, and
 the Opportunity ID the trigger logged—opens that Opportunity in Salesforce,
 follows its Account lookup, finds Industry blank]
"Ah, need to add null check for Industry field."
[5 minute fix]
```

### 2. Use Enrichment Data for Root Cause Analysis

Always check:

* **Recent audit trail entries:** Did something change recently?
* **Governor limits:** Is this a performance issue disguised as a logic error?
* **Related records:** Open the records the log referred to—is a parent or lookup empty?

### 3. Leverage Enrichment for Team Communication

When escalating an error to another team, include Pharos log link (not just error message). The enriched context helps them understand the issue without back-and-forth.

### 4. Configure Data Masking for Sensitive Fields

If you log data that includes PII, financial information, or credentials, set up data masking rules to redact sensitive values automatically.

## Limitations

Enrichment can only draw on platform data that is still available to Salesforce, which sets a few practical boundaries.

### Enrichment Has Boundaries

| What Pharos Can Enrich                                                                                                  | What Pharos Cannot Enrich                                                         |
| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Platform data available via Salesforce APIs—`User`, `AuthSession`, `SetupAuditTrail`, `DeployRequest`, limits, metadata | External system data (unless brought into Salesforce)                             |
| Setup Audit Trail entries within the 48-hour window Pharos queries                                                      | Setup changes older than that window                                              |
| IDs of records referenced in the log, with their object types                                                           | Field values from your business records—Pharos stores record IDs, not record data |
| Governor limits at time of error                                                                                        | Pre-error transaction history                                                     |
| Values the error text itself contained, as Salesforce emitted them                                                      | Deleted records (if purged before enrichment)                                     |
| User, session, org and stack trace context                                                                              | Data from disconnected or archived orgs                                           |

{% hint style="warning" %}
**Asynchronous Timing:** Enrichment happens after the log is captured. In rare cases (extreme org load, platform event backlog), there may be a 30-60 second delay before enriched data appears. The raw log is always visible immediately—only the enriched context has potential latency.
{% endhint %}

## Summary

Log enrichment transforms raw error messages into actionable intelligence by automatically adding contextual metadata that would otherwise require manual investigation:

**What Gets Enriched:**

* User context (profile, role, licence type, session)
* Record context (IDs of records referenced, with object types)
* Governor limit consumption (SOQL, DML, CPU, Heap)
* Enhanced stack traces (code context, call chain)
* Environment snapshots (org, timestamp, transaction ID)
* Audit trail correlation (recent changes, deployments)
* Flow-specific context (diagrams, values reported in the flow error)
* Integration payload details (request/response, latency)

**Key Benefits:**

* **90% reduction in investigation time:** From 35 minutes to 3 minutes per error
* **Zero transaction impact:** Enrichment runs asynchronously in separate context
* **Pattern recognition:** Enables proactive error detection and impact-based prioritization
* **Context-aware alerting:** Enriched data powers smart notification rules
* **Automatic operation:** No configuration required—masking and retention are the only related settings

**The Enrichment Promise:** Every log becomes a complete diagnostic snapshot with everything needed to understand, triage, and resolve the problem—automatically.
