> 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-lifecycle.md).

# Log Lifecycle

Understand the log processing flow from the moment a log is entered through different entry points.

A log's journey through Pharos begins at one of three entry points and ends as a fully enriched, queryable record in the issue tracker. Understanding this lifecycle helps explain how Pharos delivers real-time observability without impacting transaction performance.

{% hint style="success" %}
**Performance Promise:** The entire lifecycle from error occurrence to processed log typically completes within 1-5 seconds, with zero impact on the original transaction's governor limits or execution time.
{% endhint %}

## Entry Points

Logs enter Pharos through three distinct mechanisms, each optimized for different scenarios. Every log—regardless of entry point—flows through the same processing pipeline, ensuring consistent enrichment and aggregation.

| Entry Mechanism                | Mode      | Latency         | Best For                         | Code Changes Required    |
| ------------------------------ | --------- | --------------- | -------------------------------- | ------------------------ |
| **Automated Email Collection** | Passive   | 2-10 seconds    | Unhandled Apex/Flow exceptions   | None                     |
| **Periodic Mining**            | Proactive | Scheduled cycle | Batch jobs, silent bulk failures | None                     |
| **Platform Events (Triton)**   | Explicit  | 1-3 seconds     | Custom instrumentation, tracing  | Developer implementation |

### Automated Email Collection

Salesforce sends exception emails when unhandled errors occur—Apex failures, Flow exceptions, and certain Bulk API errors. Pharos monitors a designated email address and automatically ingests these notifications as they arrive.

When Salesforce sends an exception email, Pharos's email handler parses the message body, extracts the error details, and initiates the processing pipeline. The email itself contains information about the error type, user, timestamp, and stack trace or failure message.

**Key Characteristics:**

* Requires no code changes—works immediately after setup
* Passive monitoring—Pharos reacts to what Salesforce sends
* Specialized parsers handle different formats (Apex vs. Flow vs. Bulk API)
* Captures unhandled exceptions that would otherwise only be visible as ephemeral emails

**Primary Use Case:** Baseline error monitoring for production environments where you need comprehensive exception tracking without any instrumentation overhead.

### Periodic Mining

Not all errors generate emails. Bulk API failures, for example, sit silently in job queues unless explicitly checked. Pharos runs scheduled mining jobs that periodically query Salesforce for errors that wouldn't otherwise surface.

Pharos queries `AsyncApexJob`, `BatchApexErrorEvent`, and `BulkApiResultEvent` on a scheduled cycle, which is configurable in some cases. When new failures are detected, they're pulled into the processing pipeline just like email-sourced logs.

**Key Characteristics:**

* Proactive discovery—actively hunts for errors rather than waiting
* Discovers silent failures before users report them
* Configurable schedule balances freshness with API usage
* Essential for batch operations that don't trigger email notifications

**Primary Use Case:** Catching batch job failures, Data Loader errors, and integration bulk operations—especially scheduled jobs that run overnight and might fail unnoticed until business hours.

### Platform Events (Triton Logger)

For custom instrumentation and real-time logging, Pharos provides the Triton logger. Developers explicitly publish log platform events from Apex, LWC, or Flows, giving them complete control over what gets logged and when.

Code calls a Triton logging method, which publishes a platform event containing the log payload. Pharos subscribes to these events via a platform event trigger and processes them identically to automated logs.

**Key Characteristics:**

* Explicit control—logs only occur when code requests them
* Most flexible entry point with customizable payloads
* Supports transaction tracing across multiple contexts
* Works from any Salesforce execution context (Apex, Flow, LWC)

**Primary Use Case:** Instrumented workflows where you need visibility beyond unhandled errors—transaction tracing, performance monitoring, custom business logic milestones, and handled exception tracking.

## Processing Stages

Once a log enters Pharos through any entry point, it flows through a consistent six-stage pipeline that transforms raw errors into enriched, aggregated diagnostic records:

```
Entry Point → Parse → Categorize → Fingerprint → Enrich → Aggregate → Persist
```

### 1. Raw Capture and Parsing

The first stage extracts structured data from the raw input. For emails, this means parsing message bodies to find error messages, stack traces, and metadata. For mining, it means transforming query results into log fields. For platform events, the data is already structured.

Parsing adapts to the source format—Apex exception emails look different from Flow failure emails, which look different from Bulk API job results. Pharos maintains specialized parsers for each scenario to ensure complete data extraction.

### 2. Categorization

With structured data in hand, Pharos determines what type of log this is—Apex, Flow, Bulk API, or a custom Triton log. Categorization affects how the log is stored, what fields are populated, and how it's presented in the UI.

Category assignment relies on pattern matching:

* "Flow Interview" in message → Flow log
* Stack trace with Apex class → Apex log
* Bulk API job failure → Bulk API log
* Custom platform event → Triton log

### 3. Fingerprinting

Pharos extracts the **invariant signature** of the error—the parts that remain constant across occurrences. For an Apex error, this might be the exception type and the line number in the code. For a Flow error, it's the flow name and the failed element.

{% hint style="info" %}
**The Power of Fingerprinting:** Instead of viewing 500 individual logs for the same null pointer exception, you see one Issue with 500 occurrences. This transforms overwhelming log noise into manageable problem sets.
{% endhint %}

### 4. Enrichment

The log is augmented with contextual metadata that wasn't present in the raw error. Pharos queries Salesforce for user details, record values, governor limits, audit trail changes, and related object information. This happens **asynchronously** to avoid slowing down the original transaction.

**What Gets Added:**

* User profile information and role hierarchy
* Related record field values and audit history
* Governor limit consumption at time of error
* Organization metadata and custom settings
* Related log occurrences and patterns

Enrichment is where Pharos adds the most value—a sparse error message becomes a complete diagnostic snapshot with everything needed to understand and resolve the problem.

### 5. Issue Assignment

Using the fingerprint, Pharos checks if an Issue already exists for this error pattern. If so, the log is linked to the existing Issue and statistics are updated (occurrence count, last occurred date, impacted users). If not, a new Issue is created.

This aggregation is automatic and continuous. As logs arrive, they flow into their corresponding Issues, building a real-time picture of system health without manual grouping.

### 6. Persistence

The fully processed log is saved as a custom Salesforce object. At this point it's queryable, reportable, and visible in the Pharos UI. The log is **immutable**—it represents a point-in-time snapshot of what happened and when.

{% hint style="warning" %}
**Data Integrity:** Logs cannot be altered retroactively. This immutability is essential for audit trails and root cause analysis—you can trust that the data reflects what actually occurred.
{% endhint %}

## Timing and Latency

The entire lifecycle from error occurrence to processed log typically completes within **1-5 seconds**, depending on org load and enrichment complexity. However, the observed latency varies by entry point:

| Entry Point      | Discovery Latency   | Processing Time | Total Latency          | Primary Factor     |
| ---------------- | ------------------- | --------------- | ---------------------- | ------------------ |
| Email Collection | 2-10 seconds        | <1 second       | 2-10 seconds           | Email delivery     |
| Periodic Mining  | One scheduled cycle | <1 second       | Dominated by the cycle | Scheduled interval |
| Platform Events  | Immediate           | <1 second       | 1-3 seconds            | Event delivery     |

**What This Means:**

* **Real-time monitoring:** Platform events provide near-instant visibility for instrumented code
* **Proactive detection:** Mining discovers silent failures before they escalate, trading latency for completeness
* **Baseline coverage:** Email collection balances speed with zero-configuration deployment

## Asynchronous Architecture

Processing happens **asynchronously** to ensure that user-facing transactions aren't delayed by log creation. When an error occurs, Salesforce handles it (or sends an email, or the developer publishes an event), and then the transaction completes. Pharos processing occurs afterward in a separate context.

This architecture delivers critical benefits:

**Performance Isolation**

* Even if enrichment requires several SOQL queries to gather context, those queries don't count against the original transaction's governor limits
* User-facing operations complete at full speed regardless of log processing complexity

**Resilient Queueing**

* Platform events act as the queueing mechanism with guaranteed at-least-once delivery
* Logs will be processed even if the org experiences temporary load spikes
* Events queue gracefully and process as capacity becomes available

**Scalability**

* Processing throughput scales independently of transaction volume
* High-traffic periods don't create backlogs that impact observability freshness

## Resilience and Error Handling

Pharos processing itself is monitored and error-resistant. The system handles edge cases gracefully:

**Partial Enrichment**

* If enrichment fails (e.g., a related record was deleted between error occurrence and processing), Pharos logs what it can and marks the log with a processing status indicator
* The log remains visible and actionable, even if some contextual data is unavailable

**Event Retry Logic**

* If the platform event subscriber encounters an exception, the event will be retried according to Salesforce's retry logic
* Transient failures don't result in lost logs

**Pipeline Monitoring**

* Pharos maintains processing metrics so administrators can monitor pipeline health
* Anomalies in processing rates or failure patterns trigger alerts

## Data Integrity and Archival

Pharos maintains strict data integrity guarantees:

**Immutability**

* Logs are immutable once created—they represent a point-in-time snapshot of what happened
* No retroactive alterations are possible, ensuring audit trail reliability
* You can trust that the data reflects what actually occurred, not a modified version

**Deletion and Archival**

* When a log is deleted (via retention rules or manual removal), it's permanently removed from active storage
* Before deletion, Pharos supports archival to Big Objects or external systems
* Historical data is preserved even when active storage is reclaimed

{% hint style="info" %}
**Compliance-Ready:** Immutable logs with audit-trail archival support regulatory requirements for data retention and forensic investigation.
{% endhint %}

## Summary

The log lifecycle is a carefully orchestrated sequence: **capture → parse → categorize → fingerprint → enrich → aggregate → persist**. Three entry points (email, mining, platform events) funnel all errors into a unified processing pipeline that:

* Runs **asynchronously** to avoid impacting transaction performance
* Completes within **1-5 seconds** for most logs
* Scales gracefully under load with resilient queueing
* Produces **fully enriched diagnostic records** with complete context
* Maintains **immutable audit trails** for compliance and forensics

This architecture enables comprehensive observability without performance overhead, ensuring that every error—no matter how obscure—is captured, enriched, and made actionable.
