> 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/why-issues.md).

# Why Issues?

Understand the value of issues vs logs and why aggregation makes issue  management easier and more streamlined.

Issues represent a fundamental shift in how you think about errors—moving from individual events to patterns. This aggregation makes the difference between overwhelming noise and actionable intelligence.

## The Problem with Raw Logs

When monitoring solely at the log level:

**Volume Overwhelms:**

* Same error occurs 1,000 times → 1,000 log records to review
* No clear way to know if these are related
* Each occurrence treated as a separate incident

**Duplicate Effort:**

* Developer A investigates occurrence #1
* Developer B investigates occurrence #47
* Both spend 2 hours reaching the same conclusion

**Lost Context:**

* Can't see the big picture
* Don't know if error is growing or shrinking
* Can't measure user impact without manual counting

**Alert Fatigue:**

* 1,000 errors → 1,000 notifications
* Team starts ignoring alerts
* Critical issues lost in the noise

## The Solution: Issue Aggregation

By grouping identical errors into Issues:

**Volume Becomes Manageable:**

* 1,000 log occurrences → 1 Issue record
* Single view shows aggregate metrics
* One investigation covers all occurrences

**Impact Becomes Visible:**

* Automatic calculation of users affected
* Clear understanding of data scope
* Trend analysis over time

**Prioritization Becomes Data-Driven:**

* Sort by user impact, not chronology
* See which issues are growing
* Identify systemic vs. one-off problems

**Alerting Becomes Actionable:**

* Alert once per unique issue
* Updates don't trigger new alerts
* Critical issues stand out

## Real-World Example

The following scenario contrasts the two approaches on the same incident, showing what aggregation saves in practice.

### Scenario: Validation Rule Change

On May 15, a validation rule is modified making the "Industry" field required on Accounts. Over the next month, this causes 3,247 failures across 47 users.

**Without Issue Aggregation:**

```
May 15: 15 log records created
May 16: 87 log records created
May 17: 143 log records created
...
[3,247 total log records]

Questions:
- Are these all the same problem?
- How many users are affected?
- Is this getting better or worse?
- When did this start?

Developer Time: 
- 6 hours investigating the "same" error multiple times
- Spreadsheet analysis to count unique users
- Manual review of each log to find patterns
```

**With Issue Aggregation:**

```mermaid
graph TD
    A[Issue: DML Exception Required field missing Industry]
    A --> B[First Seen: May 15, 2024]
    A --> C[Last Seen: 2 hours ago]
    A --> D[Total Occurrences: 3,247]
    A --> E[Unique Users: 47]
    A --> F[Trend: Daily - stable ~107/day]
    A --> G[Objects: Account - 3,247 records]
    A --> H[Functional Area: Apex]
```

**Time Saved:** 4.5 hours\
**Business Impact:** All 47 users' workflows restored

## Architecture Reference

Issues are created through the fingerprinting process:

```mermaid
graph TD
    A[LOG RECORDS<br/>Log 1, Log 2, Log 3 ... Log 3,247]
    B[ISSUE RECORD<br/>Fingerprint: abc123...<br/>3,247 occurrences / 47 unique users / Status: New]
    C[ACTIONABLE WORKFLOWS<br/>Triage once - Create one Jira ticket<br/>Track resolution progress - Measure recurrence]
    A -->|Fingerprinting Algorithm<br/>Normalizes IDs, timestamps, preserves error signature| B
    B -->|Enables| C
```

→ [Learn more about fingerprinting](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-processing/log-fingerprinting.md)

## When to Use Issues vs. Logs

Issues and logs serve complementary purposes—reach for the Issue view for strategic decisions and the log view for tactical debugging.

**Use Issue View When:**

* Triaging: What should we fix first?
* Prioritizing: Which errors have the most impact?
* Tracking: Are we reducing error rates?
* Reporting: What's our system health trend?

**Use Log View When:**

* Debugging: What was the specific context for this occurrence?
* Investigation: What record IDs were involved?
* User support: Did this specific user's transaction fail?
* Deep analysis: What were the exact variable values?

**Both Are Essential:**\
Issues for strategic decisions, Logs for tactical debugging.

## Measuring Issue Aggregation Value

Track these metrics to quantify the benefit:

| Metric                            | Before Issues   | With Issues     |
| --------------------------------- | --------------- | --------------- |
| **Time to Triage**                | 4-6 hours/week  | 30-60 min/week  |
| **Duplicate Investigations**      | 30% of dev time | <5% of dev time |
| **Alert Volume**                  | 500+ per day    | 10-20 per day   |
| **Mean Time to Identify Pattern** | 2-3 days        | Immediate       |

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

Explore [Issue Details](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-details.md) to understand what information is available on each Issue record, or jump to [Issue Lifecycle](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker/issue-lifecycle.md) to learn how Issues progress from creation to resolution.
{% endhint %}
