> 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-storage/native-data-model.md).

# Native Data Model

Learn about the Pharos log data model and how logs are stored as custom objects.

Pharos leverages Salesforce custom objects to store all log and issue data within your org. This native approach ensures data remains under your control while providing seamless integration with Salesforce's platform capabilities.

## Overview

The Pharos data model consists of custom objects that store logs, issues, and configuration data. All data persists in your Salesforce org as standard custom object records, making them accessible through the tools and processes you already use every day.

**What this means for you:**

* ✅ Build standard Salesforce reports and dashboards
* ✅ Query data using SOQL and APIs
* ✅ Export records using familiar data export tools
* ✅ Rely on Salesforce's built-in backup and recovery
* ✅ Automatic security, compliance, and data management

{% hint style="success" %}
**Key Advantage:** If you know how to work with Salesforce custom objects, you already know how to work with Pharos data. No new tools or skills required.
{% endhint %}

## Core Objects

### Log Object (Log\_\_c)

The primary object for storing individual log entries. Each log record represents a single execution or error event in your Salesforce org, capturing the complete context of what happened. Records are auto-numbered (`LOG-00001`) and carry roughly 84 fields.

**What it stores:**

| Field Category     | Purpose               | Example Fields                                         |
| ------------------ | --------------------- | ------------------------------------------------------ |
| **Event Details**  | What happened         | Summary, Description, Error Message, Stack Trace       |
| **Classification** | Log organization      | Category (e.g., Apex, Flow, Bulk API), Functional Area |
| **Temporal**       | When it occurred      | Created Date, Execution Timestamp                      |
| **Context**        | Who/What triggered it | User, Affected Records, Related Object Types           |
| **Grouping**       | Issue relationship    | Parent Issue (lookup), Parent Log (self-lookup)        |

**Key characteristics:**

* Each log = one occurrence of an event
* Immutable snapshot of the moment of failure
* Enriched with metadata for searching and filtering
* Linked to parent Issue for aggregation

### Issue Object (Issue\_\_c)

The issue object aggregates similar logs into a single manageable entity. Rather than dealing with dozens or hundreds of individual log entries for the same problem, Pharos groups logs with identical fingerprints together under one issue record. Records are auto-numbered (`ISS-00001`) and carry roughly 44 fields.

**What it stores:**

| Field Category       | Purpose          | Key Fields                                                              |
| -------------------- | ---------------- | ----------------------------------------------------------------------- |
| **Problem Summary**  | What's wrong     | Summary, Key, Category, Type                                            |
| **Lifecycle**        | Current state    | Status (New/Triaged/Actioned/In Progress/In Review/Completed/Duplicate) |
| **Occurrence Stats** | How often        | Log Count, First Occurred, Last Occurred, Frequency                     |
| **Impact Metrics**   | Who's affected   | Impacted Users, Impacted Objects, Impacted Records                      |
| **Volume Trends**    | Pattern analysis | Daily Volume, Peak Period, Trend Direction                              |

**Key characteristics:**

* One issue = multiple occurrences of same problem
* Dynamic statistics that update with each new log
* Lifecycle tracking from detection to resolution
* Aggregate view for prioritization

{% hint style="info" %}
**Issue vs Log:** A validation rule failing 500 times creates **500 log records** but only **1 issue record**. The issue shows aggregate impact while logs preserve individual occurrence details.
{% endhint %}

### Supporting Objects

Behind the two primary objects, a set of supporting objects powers configuration, automation, and advanced capabilities. These are managed through the Pharos admin interface and generally don't require direct interaction.

| Category                 | Objects                                                                       | Purpose                                                                 |
| ------------------------ | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Rules & Actions**      | `Rule__c`, `Action__c`, `RuleFilter__c`, `RuleAction__c`                      | Define alerting triggers, notification routing, and automated responses |
| **Tracing**              | `Trace_Request__c`, `Trace_Result__c`, `Trace_Schedule__c`                    | Configure and store results from issue tracing operations               |
| **Event Monitoring**     | `Event__c`, `EventAction__c`, `Event_Monitoring__c`                           | Track platform events and monitoring metrics                            |
| **Governor Limits**      | `Limits__c`                                                                   | Capture governor limit snapshots associated with log records            |
| **Connected Orgs**       | `Connected_Org__c`                                                            | Manage multi-org observability configurations                           |
| **Integration Settings** | `Jira_Settings__c`, `Slack_Settings__c`, `Pager_Duty_Settings__c`, and others | Store credentials and configuration for external integrations           |
| **Platform Settings**    | `Pharos_Settings__c`, `Logger_Settings__c`                                    | Control platform behavior and logging defaults                          |

{% hint style="info" %}
**Configuration, Not Clutter:** Supporting objects store the rules, settings, and integration details that power Pharos features. They're managed through dedicated admin interfaces—you rarely need to interact with them as raw records.
{% endhint %}

### Platform Events

Pharos uses platform events for asynchronous processing within its architecture.

| Event          | Purpose                                                    |
| -------------- | ---------------------------------------------------------- |
| `Log_Event__e` | High-volume event that drives log ingestion and processing |
| `AI_Event__e`  | Handles AI-powered analysis requests for issues            |

These events are internal to the Pharos processing pipeline and are not intended for direct subscriber use.

## Storage Characteristics

### Data Storage Impact

All Pharos custom object records count against your org's **Data Storage** allocation:

| Record Type                         | Typical Size | Impact                             |
| ----------------------------------- | ------------ | ---------------------------------- |
| **Simple Log**                      | 2-5 KB       | Low per-record, scales with volume |
| **Complex Log** (large stack trace) | 10-20 KB     | Higher per-record impact           |
| **Issue Record**                    | 1-2 KB       | Minimal (aggregate stats only)     |
| **Configuration**                   | < 1 KB       | Negligible                         |

**Calculation example:**

* 1,000 logs/day @ 5 KB average = 5 MB/day = \~1.8 GB/year

### File Storage Impact

**Typically zero.** Pharos uses File Storage only if:

* Large log payloads are stored as attachments (uncommon)
* Debug logs exceed inline storage limits (rare)

Most deployments never touch File Storage.

### Big Object Storage (Archival)

When using local archival retention rules, old logs move to Big Objects:

| Characteristic | Details                                                     |
| -------------- | ----------------------------------------------------------- |
| **Allocation** | 1 million records free per org (separate from Data Storage) |
| **Cost**       | Frees up Data Storage when logs are archived                |
| **Access**     | Limited query capabilities (SOQL only, no UI)               |
| **Use Case**   | Long-term archival without consuming primary storage        |

{% hint style="info" %}
**Storage Optimization:** Archiving to Big Objects preserves historical data while freeing up expensive Data Storage for active logs.
{% endhint %}

{% hint style="warning" %}
**Evolving Capability:** Big Object archival is a newer part of the retention feature set. Confirm current availability and behavior with your Pharos contact before relying on it as part of a critical retention strategy.
{% endhint %}

## Object Relationships

The Pharos data model follows a hierarchical structure:

```mermaid
graph TD
    A[Organization]
    A --> B[Issues]
    B --> C[Logs]
    C --> D[Related Records - Accounts, Contacts, etc.]
```

**Relationship types:**

| Relationship               | Type                       | Reason                                                                                                                                                           |
| -------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Log → Issue**            | Lookup (not master-detail) | Allows flexible data management and independent retention                                                                                                        |
| **Log → Parent Log**       | Self-lookup                | Links logs that share a transaction Id, flow interview GUID, or request Id (external-Id matching on `Transaction_Id__c` / `Interview_GUID__c` / `Request_Id__c`) |
| **Log → Affected Records** | Lookup                     | Links to specific Salesforce records involved in error                                                                                                           |
| **Issue → Logs**           | Implicit (via log lookups) | Issue shows count and can query related logs                                                                                                                     |
| **Cross-Org**              | External Lookup            | For Connected Orgs scenarios                                                                                                                                     |

{% hint style="warning" %}
**Why Not Master-Detail?** Lookup relationships (instead of master-detail) allow logs to be deleted individually via retention rules without cascading deletes. Pharos handles issue cleanup separately: if all logs under an issue are removed, the issue is automatically deleted.
{% endhint %}

## Data Access Patterns

### Query Considerations

Pharos objects support standard SOQL queries like any Salesforce custom object:

| Consideration   | Best Practice                       | Why                                                  |
| --------------- | ----------------------------------- | ---------------------------------------------------- |
| **Indexes**     | Use indexed fields in WHERE clauses | Commonly filtered fields pre-indexed for performance |
| **Selectivity** | Always use WHERE clauses            | Limits result sets, prevents timeouts                |
| **Pagination**  | Use LIMIT and OFFSET                | Handles large datasets without hitting query limits  |
| **Query Scope** | Filter by date range or category    | Reduces rows scanned, improves response time         |

**Example selective query:**

```sql
SELECT Id, pharos__Summary__c, CreatedDate 
FROM pharos__Log__c 
WHERE CreatedDate = LAST_N_DAYS:30 
  AND pharos__Category__c = 'Apex'
LIMIT 100
```

### Permissions and Sharing

Pharos inherits Salesforce's standard permission model—no special security mechanisms:

| Security Layer           | Purpose                     | Example                                                                                                                                              |
| ------------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Permission Sets**      | Object-level access         | `Log_Admin`, `Log_Read_Write`, `Log_Read` (shipped separately via the [pharos-permissions](https://resources.pharos.ai/pharos-permissions) download) |
| **Field-Level Security** | Sensitive field restriction | Hide Debug Context field from certain users                                                                                                          |
| **Sharing Rules**        | Record-level visibility     | Share logs from Sales functional area with Sales team only                                                                                           |
| **Object Permissions**   | CRUD operations             | Create/Read/Edit/Delete control per profile                                                                                                          |

👉 See [Access Controls](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/access-controls.md) for detailed configuration guidance.

## Data Lifecycle

The journey of a log record from creation to eventual archival or removal:

```
Event Occurs → Log Created → Fingerprinted → Matched/Grouped → Active Period → Retention → Archive/Remove
```

### 1. Creation

When an event occurs in Salesforce (error, flow execution, etc.):

1. **Capture** - Pharos creates log record with full context
2. **Fingerprint** - Algorithm identifies unique characteristics
3. **Match** - Compare against existing issues
4. **Group** - Update existing issue OR create new issue

### 2. Active Period

Logs remain fully accessible:

* **For Debugging** - Complete details available for analysis
* **For Issues** - Statistics update as new occurrences captured
* **For Users** - Triage, comment, mark resolved

### 3. Retention Evaluation

Retention rules evaluate periodically:

| Condition           | Action               | Result                                |
| ------------------- | -------------------- | ------------------------------------- |
| **Age < Threshold** | No action            | Log remains active                    |
| **Age ≥ Threshold** | Apply retention rule | Archive and/or remove                 |
| **Always**          | N/A                  | Issue persists (even if logs removed) |

### 4. Archival (Optional)

When local archival is configured:

1. ✅ Identify logs older than retention threshold
2. ✅ Copy log data to Big Object storage
3. ✅ Remove original log from custom objects
4. ⚠️ Archived data queryable via SOQL (no UI access)

{% hint style="info" %}
**Issue Cleanup:** If all logs under an issue are removed (e.g., by retention rules), the issue is automatically deleted. Issues with at least one remaining log are preserved along with their impact metrics and lifecycle history.
{% endhint %}

## Technical Specifications

### Object Limits

Pharos objects follow standard Salesforce limits:

| Limit Type             | Value                   | Implications                       |
| ---------------------- | ----------------------- | ---------------------------------- |
| **Total Records**      | Limited by Data Storage | Manage with retention rules        |
| **SOQL Query Results** | 50,000 records max      | Use pagination for large datasets  |
| **API Calls**          | Standard org limits     | Design bulk operations accordingly |
| **List View Results**  | 2,000 records           | Use filters for better targeting   |

### Performance Considerations

Query performance follows the same rules as any large Salesforce object — see [Query Considerations](#query-considerations) above for indexing and selectivity. The one factor specific to Pharos is dataset size: archiving old logs to Big Objects keeps the active dataset small, which does more for report and search speed than query tuning can once a table reaches millions of rows. [Storage Usage](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-storage/storage-usage.md) covers monitoring consumption and acting on it.

{% hint style="warning" %}
**Performance Tip:** Unrestricted queries on tables with millions of records can timeout. Always filter by date range or category when building reports or queries.
{% endhint %}

## Integration with Salesforce

### Native Benefits

Storing data as custom objects provides automatic operational advantages:

| Benefit                  | How It Works                    | Value                                                 |
| ------------------------ | ------------------------------- | ----------------------------------------------------- |
| **🔒 Security**          | Inherits org security model     | Field-level security, encryption, sharing rules apply |
| **☁️ Backup**            | Included in Salesforce backups  | No additional configuration needed                    |
| **✅ Compliance**         | Follows org compliance settings | HIPAA, SOX, GDPR automatically covered                |
| **🔄 Disaster Recovery** | Salesforce platform handles     | Enterprise-grade infrastructure                       |
| **📊 Reporting**         | Native Salesforce analytics     | Build custom reports and dashboards                   |

### Standard Tools

Access Pharos data with familiar Salesforce tools—no new skills required:

| Tool                     | Use For             | Example                           |
| ------------------------ | ------------------- | --------------------------------- |
| **Data Loader**          | Bulk export/import  | Back up all logs off-platform     |
| **Workbench**            | Data exploration    | Ad-hoc SOQL queries and analysis  |
| **Developer Console**    | Direct queries      | Investigation and troubleshooting |
| **Reports & Dashboards** | Visualizations      | Custom log trend analysis         |
| **SOQL (Apex/API)**      | Programmatic access | Custom integrations               |

{% hint style="warning" %}
**Caution:** While you *can* directly manipulate Pharos objects through Data Loader or APIs, prefer using Pharos's built-in interfaces. Direct manipulation bypasses business logic and can cause data inconsistencies.
{% endhint %}

{% hint style="success" %}
**Bottom Line:** If you know Salesforce, you know how to work with Pharos data. No proprietary tools or external systems required.
{% endhint %}
