> 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/issue-tracker/issue-lifecycle/creation.md).

# Creation

Understand when a new Issue is created vs leveraging an existing issue through fingerprinting.

Issues are automatically created the first time Pharos encounters a unique error pattern. Understanding how this creation process works—and when errors get grouped versus separated—is fundamental to effective issue management.

## Automatic Issue Creation

When a new log record is generated (from an Apex exception, flow failure, process builder error, or bulk API failure), Pharos immediately begins analyzing it through the fingerprinting engine. This process is near-instantaneous and requires no manual intervention.

**Initial Creation Flow:**

1. **Log arrives** → Pharos receives an error notification (via Apex email service, platform event, or direct logging)
2. **Fingerprint calculated** → System analyzes error signature, stack trace, flow path, and metadata
3. **Fingerprint comparison** → Searches existing issues for matching fingerprint
4. **Decision point**:
   * **No match found** → New Issue created
   * **Match found** → Log linked to existing Issue

When a new Issue is created, its status defaults to `New` and priority defaults to `Medium`. The Issue inherits key attributes from the first log, including category, functional area, and type.

## Fingerprinting: The Core Mechanism

Fingerprinting is the deterministic algorithm that determines whether two errors represent the same underlying problem or different issues. Think of it as a "DNA signature" for errors.

### What Gets Fingerprinted

The fingerprint algorithm considers different factors based on log type:

**Apex Errors:**

* Stack trace sequence (class names and method names)
* Exception type (`DmlException`, `NullPointerException`, etc.)
* Error message pattern (variable values normalized out)
* Object types involved

**Flow Errors:**

* Flow API name and version
* Element sequence (decision paths, loops, actions)
* Element API names
* Failure point in execution path

**Process Builder Errors:**

* Process definition name and version
* Action sequence
* Criteria node path
* Flow/Apex called from process

**Bulk API Errors:**

* Operation type (insert, update, upsert, delete)
* Object type
* Error message pattern
* API version

### What Gets Normalized (Ignored)

To group related errors correctly, certain variable data is normalized:

* **Record IDs** → Treated as generic identifiers
* **Timestamps** → Not factored into fingerprint
* **User IDs** → Normalized unless user-context is error-critical
* **Line numbers** → Excluded (code can shift)
* **Variable values** → Pattern recognized, specific values ignored

### Examples of Fingerprint Behavior

The following examples show how the algorithm decides whether two errors share a fingerprint or belong to separate Issues.

**Example 1: Same Fingerprint**

```
Log A: DmlException on Account insert, line 156 in OpportunityTriggerHandler.afterInsert
       Stack: TriggerHandler → ValidationHelper → AccountService
       Record: 001xx000003ABCD
       
Log B: DmlException on Account insert, line 156 in OpportunityTriggerHandler.afterInsert  
       Stack: TriggerHandler → ValidationHelper → AccountService
       Record: 001xx000003WXYZ
```

→ **Same fingerprint** (record IDs normalized, stack trace identical)

**Example 2: Different Fingerprints**

```
Log A: DmlException on Account insert
       Stack: TriggerHandler → ValidationHelper → AccountService
       
Log B: DmlException on Account insert  
       Stack: TriggerHandler → DuplicateCheckService → AccountService
```

→ **Different fingerprints** (execution path differs, indicates different code branch)

**Example 3: Flow Version Changes**

```
Log A: Flow "Account_Creation_Flow" version 12 fails at element "Validate_Industry"
       
Log B: Flow "Account_Creation_Flow" version 13 fails at element "Validate_Industry"
```

→ **Different fingerprints** (flow version considered significant), but **automatically related** as similar issues

## When a New Issue Is Created

A new Issue is created in these scenarios:

1. **First occurrence of error pattern**
   * Never seen this stack trace before
   * New combination of flow elements failing
   * Novel error message pattern
2. **Code path changes**
   * Refactored code now executes different sequence
   * Flow logic modified (new branches, different element order)
   * New exception type thrown from same location
3. **Version bumps** (Flow-specific)
   * Flow version incremented
   * New Issue created, but related to prior version's Issue
4. **Apex class refactoring**
   * Class renamed or moved to different package
   * Method sequence altered
   * New helper classes introduced in call stack

## When an Existing Issue Is Reused

An existing Issue is reused when:

1. **Exact fingerprint match**
   * Identical execution path
   * Same error message pattern
   * Matching stack trace sequence
2. **Recurring errors**
   * Same validation rule failing repeatedly
   * Persistent CPU timeout on scheduled job
   * Ongoing null pointer in specific trigger
3. **Multiple users hitting same error**
   * UI flow breaks for different users
   * Batch job fails across different data sets
   * Integration timeout affects multiple transactions

## Issue Relationships: Broader Fingerprint Tiers (Hash 2 and Hash 3)

Even when the exact fingerprint doesn't match, Pharos can still recognize that two Issues are probably connected. Alongside the primary fingerprint (`pharos__Hash_1__c`) used to group logs into an Issue, each Log carries two progressively looser fingerprint tiers — [Log Fingerprinting](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-processing/log-fingerprinting.md) explains how they're built:

* **Hash 2** (`pharos__Hash_2__c`) → A looser fingerprint than Hash 1 (e.g., similar stack trace with minor variation)
* **Hash 3** (`pharos__Hash_3__c`) → A looser fingerprint still, currently evaluated only for Flow and Process Builder logs

When a new Issue is created, Pharos checks other open Issues (and, in some cases, older Completed or Duplicate Issues without a related Issue yet) for a Log sharing that Hash 2 value — or, for Flow/Process Builder, that Hash 3 value. A match sets the Issue's `pharos__Related_Issue__c` lookup to point at the matching Issue (a Hash 2 match takes priority over Hash 3). This appears in the **Related Issues** list on the Issue page — there's no color coding or match-confidence score, just the lookup relationship itself.

This automatic relating is valuable when:

* Code refactoring creates a new Hash 1 but the underlying error is still similar
* Flow versions change slightly
* Related functionality fails in parallel

## The Relationship Between Logs and Issues

Think of it this way:

```mermaid
graph TD
    subgraph Logs["LOGS - Raw Events"]
        L1[Log 1: 9:00 AM - Error A]
        L2[Log 2: 9:15 AM - Error A - same fingerprint]
        L3[Log 3: 10:30 AM - Error A - same fingerprint]
        L4[Log 4: 11:00 AM - Error B - different fingerprint]
    end
    subgraph Issues["ISSUES - Aggregated Problems"]
        I1[Issue 1: Logs 1, 2, 3 - 3 occurrences]
        I2[Issue 2: Log 4 - 1 occurrence]
    end
    Logs -->|Fingerprinting| Issues
```

**Key Insight:** You fix **one Issue**, not thousands of logs. When you resolve Issue #1, all 3,247 occurrences stop happening.

## Data Inheritance from First Log

When an Issue is created, certain fields are populated from the **first log** that created it:

**Inherited Fields:**

* **Category** (Apex, Flow, Process Builder, etc.)
* **Type** (DML Exception, Flow Interview Exception, etc.)
* **Functional Area** (if stamped on log)
* **Running User** (first occurrence user)
* **Environment** (Production, Sandbox, etc.)

**Calculated Fields (updated dynamically):**

* **Log Count** → Number of related logs
* **First Occurred** → Timestamp of Issue creation
* **Last Occurred** → Most recent log timestamp
* **Users Impacted** → Deduplicated user count
* **Records Impacted** → Deduplicated record count
* **Average Frequency** → Average gap in days between occurrence days (measured through today)
* **Daily Volume** → Total logs ÷ number of occurrence days

Average Frequency and Daily Volume are recalculated on a schedule by a batch job, not just at creation.

The Issue record maintains a lookup to this first log via the `Log` field, which allows formula fields and related lists to reference that initial occurrence.

## Issue Status Upon Creation

New Issues start with:

* **Status:** `New`
* **Priority:** `Medium` (default, should be adjusted during triage)
* **Regression:** `false`

The `New` status signals that this Issue has never been reviewed. During regular triage sessions, these should be evaluated and status changed to `Triaged` once priority is assigned.

{% hint style="success" %}
**Next Steps:**

* See [Triaging](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-lifecycle/triaging.md) to learn how to review and prioritize new Issues
* See [Duplication](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-lifecycle/duplication.md) to handle related Issues that represent the same problem
* See [Issue Relationships](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-details/issue-relationships.md) for managing related Issues
  {% endhint %}
