> 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/alerting/issue-level-alerts.md).

# Issue-level Alerts

Learn about the most common notification pattern with create-based and update-based rules.

Issue-level alerts are the recommended notification pattern for production environments. They provide notifications when issues are created or updated, avoiding notification spam while ensuring you're informed about important problems.

## Why Issue-Level Alerts?

**Issue-level alerts are recommended for production** because they aggregate multiple occurrences of the same problem into a single notification, avoiding spam:

* **One notification per problem** instead of one per occurrence
* **Easier to manage** when you have high-volume errors
* **More actionable** because you see the aggregated impact
* **Prevents notification fatigue** from repeated alerts about the same issue

## Log-Level vs Issue-Level Notifications

The two notification levels differ mainly in volume—how many alerts a given burst of errors produces.

| Aspect       | Log-Level Notifications                | Issue-Level Notifications              |
| ------------ | -------------------------------------- | -------------------------------------- |
| **Trigger**  | Every single error occurrence          | When an issue is created or updated    |
| **Volume**   | High (10 failures = 10 notifications)  | Low (10 failures = 1 notification)     |
| **Best For** | Development/sandbox environments       | Production environments                |
| **Use Case** | Active development, immediate feedback | Monitoring production, triage workflow |

**Example:** If the same flow fails 10 times:

* **Log-level:** You receive 10 separate Teams/Slack notifications
* **Issue-level:** You receive 1 notification when the issue is created, optionally another if it exceeds thresholds

## Notification Rules Structure

All notifications in Pharos are controlled through **rules** configured in the Admin section under Notifications > Issues.

Rules are evaluated top to bottom and **stop at the first match**, so exactly one notification rule fires per issue — which is what keeps a single problem from generating five alerts. The practical consequence is that order is part of the configuration: specific rules belong at the top, catch-alls at the bottom, and a catch-all placed first silently prevents everything below it from ever firing.

→ [Order of Execution](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/order-of-execution.md) covers ordering strategy, the ladder pattern, and how create and update rules interact.

## Rule Types

Issue-level notification rules are `Rule__c` records with `Type__c = "Notification"`. "Create-based" and "update-based" aren't separate Rule Type values—they're two triggering modes of the same Notification rule, controlled by the `Is_Update__c` checkbox on the rule: unchecked means the rule evaluates against newly created issues, checked means it evaluates against updates to existing issues.

### Create-Based Rules (Is\_Update\_\_c unchecked)

Trigger when a **new issue is created**. This is the most common rule type.

**When to Use:**

* You want immediate notification when a new problem appears
* You're monitoring for specific types of errors (e.g., flow failures, integration issues)
* You want different teams notified based on functional area

### Update-Based Rules (Is\_Update\_\_c checked)

Trigger when an **existing issue is updated** due to new occurrences or changing metrics.

**When to Use:**

* You want to know when an issue is getting "hot" (increasing frequency)
* You need alerts when impact grows (more users affected)
* You're monitoring for issues that cross specific thresholds

**What Triggers an Update:** When an issue has new occurrences, these fields get updated automatically:

* Last Occurred Date
* Log Count (total occurrences)
* Frequency (average days between occurrences)
* Daily Volume (occurrences per day)
* Impacted Users count
* Impacted Records count
* Impacted Objects list

***

## Explore Each Rule Type

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>🆕 Create-Based Triggering</strong></td><td>Notifications when new Issues are created—the most common alert pattern for production monitoring.</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/issue-level-alerts/create-based-triggering.md">Create-based Triggering</a></td></tr><tr><td><strong>🔄 Update-Based Triggering</strong></td><td>Notifications when existing Issues escalate—tracking when problems get worse or cross thresholds.</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/issue-level-alerts/update-based-triggering.md">Update-based Triggering</a></td></tr></tbody></table>

## Common Notification Patterns

### Pattern 1: Basic Production Monitoring

```mermaid
graph TD
    A[Rule 1 Create: Notify when any issue is created]
    A --> B[Action: Post to #prod-errors Slack channel]
```

Simple catch-all approach for smaller teams.

### Pattern 2: Functional Area Routing

```
Rule 1 (Create): Functional Area contains "Sales" → #sales-team
Rule 2 (Create): Functional Area contains "Service" → #service-team  
Rule 3 (Create): Catch-all → #platform-team
```

Routes notifications to the appropriate team based on issue characteristics.

### Pattern 3: Severity-Based Escalation

```
Rule 1 (Create): Priority = "Highest" → PagerDuty + Slack #urgent
Rule 2 (Create): Priority = "High" → Slack #high-priority
Rule 3 (Update): Log Count > 100 → Slack #escalations
Rule 4 (Update): Impacted Users Count > 10 → Slack #escalations
```

Combines create and update rules to catch both new critical issues and escalating problems.

## Managing Notification Rules

**Multiple Rules:** You can have as many notification rules as needed. Each rule can:

* Filter by any issue field (Category, Functional Area, Priority, etc.)
* Target different notification channels
* Use different message templates

**Activating/Deactivating:** Each rule can be activated or deactivated. This is useful for:

* Temporary notification rules during active development
* Seasonal monitoring (e.g., during peak periods)
* Testing new notification patterns before fully rolling out

## Best Practices

A few principles keep issue-level alerting effective from day one.

1. **Start simple:** Begin with one catch-all create rule, then add specificity as needed
2. **Use functional areas:** Filter rules by functional area to route to appropriate teams
3. **Add update rules sparingly:** Only add update rules for specific escalation scenarios
4. **Order matters:** Always put specific rules before catch-all rules
5. **Test in sandbox:** Use log-level notifications in sandbox for immediate feedback during development
6. **Deactivate when done:** If setting up temporary notifications for development, remember to deactivate them

{% hint style="success" %}
**Recommended Starting Point**

For production: Create one issue-level create rule that notifies a central channel of all new issues. As you understand your error patterns, add more specific rules.

For sandbox/UAT: Create log-level notifications temporarily during active development for immediate feedback, then deactivate when done.
{% endhint %}
