> 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/how-pharos-does-it/awareness.md).

# Awareness

How Pharos creates proactive awareness — context-rich alerts plus trends, impact, and org-level signals delivered to the right teams at the right time.

Tracking captures signals, but tracking alone isn't enough — teams need to **know** what those signals mean. The awareness stage is more than reactive alerting on errors: it's proactive insight into Salesforce operations broadly — trends, impact, and org-level health — so the right people hear about problems, and pressure building toward problems, before they escalate, with enough context to act immediately.

***

## The Challenge: Alert Fatigue

Traditional alerting often creates as many problems as it solves.

{% hint style="warning" %}
**Common Alerting Pitfalls:**

* **Too many alerts** — the same error triggers hundreds of notifications, burying the signal in noise
* **Wrong audience** — developers get paged for data quality issues; admins receive Apex stack traces
* **Missing context** — the alert says "something broke" but not what, why, or how bad
* **Noise drowns signal** — critical issues get lost in a flood of low-priority notifications

**The result:** Teams start ignoring alerts, critical issues go unaddressed, and on-call burnout sets in.
{% endhint %}

***

## The Pharos Approach: Intelligent Alerting

### Alert on Issues, Not Logs

If an error occurs 500 times, traditional systems send 500 notifications. Pharos takes a different approach — fingerprinting groups identical errors into a single Issue, and alerts are tied to that Issue rather than individual occurrences.

* First occurrence → Issue created → Notification sent
* Subsequent occurrences → Issue updated → No new notification
* **500 errors → 1 notification → Team investigates once**

### Context-Rich Notifications

Every alert includes the information a developer or admin needs to start investigating immediately:

* **Impact metrics** — how many users are affected? Which records?
* **Error details** — stack trace preview, error message, and category
* **Business context** — functional area, object types, and severity
* **Action links** — direct links to the Pharos Issue and related logs
* **Recent changes** — audit trail context showing what changed before the error appeared

### Rule-Based Routing

Route alerts based on the criteria that matter to your team:

* **Severity** — critical issues page on-call; informational ones land in a digest
* **Functional area** — sales errors go to the sales engineering team; service errors go to support
* **Error type** — Flow failures route to admins; Apex exceptions route to developers
* **Time** — business-hours-only alerts for non-critical issues; 24/7 for production emergencies

{% hint style="info" %}
**Example:** Payment processing errors → PagerDuty + #critical-channel. Sandbox flow errors → daily digest email.
{% endhint %}

***

## Beyond Alerting: Proactive Insight

Awareness isn't only "an error just happened." Pharos surfaces the signals that let teams get ahead of problems, not just react to them:

* **Trends** — is an Issue's occurrence rate climbing, flat, or trailing off?
* **Impact** — how many users or records are touched, and is that scope growing?
* **Governor-limit pressure** — [Monitoring](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/monitoring.md) flags a batch job or transaction creeping toward its limit *before* it starts failing in production
* **Org-level insight** — patterns across the whole environment, not just a single Issue, so teams can see systemic risk building rather than discovering it one incident at a time

***

## Notification Channels

Pharos integrates with the tools your teams already use, so alerts meet people where they work.

{% tabs %}
{% tab title="💬 Slack" %}

* Real-time notifications to dedicated channels
* Rich formatting with impact metrics and action links
* Support for public/private channels and @mentions
  {% endtab %}

{% tab title="💼 Microsoft Teams" %}

* Adaptive cards with error details and context
* Channel and direct message support
* Integration with Microsoft 365 workflows
  {% endtab %}

{% tab title="🚨 PagerDuty" %}

* Incident creation with escalation policies
* On-call rotation management
* Critical issue alerting with full Pharos context
  {% endtab %}

{% tab title="📧 Email" %}

* Fallback for teams without chat tools
* Digest mode for low-priority issues
* Customizable templates with relevant context
  {% endtab %}

{% tab title="🔗 Webhooks" %}

* Custom integrations with any external tool
* Datadog, New Relic, and ServiceNow integration
* Flexible JSON payloads for any use case
  {% endtab %}
  {% endtabs %}

→ [Learn more about notification channels](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels.md)

***

## Preventing Alert Fatigue

Pharos includes built-in mechanisms to keep notification volume manageable without sacrificing coverage:

* **De-duplication** — Issue-based alerting eliminates duplicate notifications by design
* **Thresholds** — alert only when an Issue's occurrence count exceeds a defined threshold
* **Suppression** — known issues marked as "Won't Fix" don't re-alert
* **Time-based rules** — non-critical alerts fire only during business hours
* **Order of execution** — prevent multiple rules from firing for the same Issue

***

## Measuring Alert Effectiveness

Track these metrics to ensure your alerting is providing value rather than creating noise:

| Metric                       | Target              | Action If Below Target |
| ---------------------------- | ------------------- | ---------------------- |
| **Alert Action Rate**        | >70% lead to action | Tighten alert criteria |
| **Mean Time to Acknowledge** | <15 minutes         | Improve routing rules  |
| **False Positive Rate**      | <10%                | Refine fingerprinting  |

***

## From Awareness to Action

Effective alerting creates awareness, but awareness alone doesn't solve problems. The next stage — **Action & Collaboration** — ensures that issues get triaged, prioritized, and assigned so they actually get resolved.

{% hint style="success" %}
**Next Step:** Learn how [Action and Collaboration](https://docs.pharos.ai/platform-overview/how-pharos-does-it/action-and-collaboration.md) transforms alerts into systematic resolution.
{% endhint %}
