> 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/monitoring/log-monitoring/monitoring-rules.md).

# Monitoring Rules

Learn about monitoring rule nuances including field grouping and spike/user impact rules.

Monitoring rules define the conditions under which Pharos should alert you to anomalous patterns in your error logs. Unlike notification rules that trigger on individual issue creation or updates, monitoring rules analyze log volumes and patterns across time windows to detect situations requiring immediate attention.

## Rule Types: Spike, Impact, and Frequency

Pharos offers three types of monitoring rule, each designed to catch a different shape of problem. What separates them is *what* they count.

**Spike rules** count events. They trigger when the number of logs in a time window exceeds your threshold, which makes them the right instrument for sudden increases in error volume — a deployment that introduces a bug in a commonly-used flow, an integration failure affecting many transactions, or a platform problem causing widespread errors. The signal is a burst.

**Impact rules** count distinct users. They trigger when the number of unique users encountering errors in the window exceeds your threshold, regardless of how many errors each of them saw. This is a different question from volume: one user hitting the same error fifty times is rarely as urgent as ten users hitting it once each, because the second pattern indicates something broad. Impact rules require you to nominate the field identifying the user.

**Frequency rules** count persistence. Rather than looking for a single burst, they fire when errors exceed the threshold consistently across *every* subdivision of the window — catching the integration that fails steadily all day, which no spike rule would ever notice because it never surges.

{% hint style="info" %}
**Choosing the Right Rule Type** Use spike rules for backend processes, batch jobs, and integrations where error count is the primary concern. Use impact rules for user-facing functionality — flows, screens, interactive processes — where experience matters more than volume. Use frequency rules for chronic, low-grade problems that never spike but never stop.
{% endhint %}

For the rule form itself, including how thresholds and aggregate intervals are configured for each type, see [Monitoring Rules](https://docs.pharos.ai/configuration-guide/monitoring/logs.md#rule-types).

## Field Grouping and Filtering

The power of monitoring rules comes from their flexibility in how they analyze log data. Through field grouping and filtering, you can create highly targeted rules that focus on specific scenarios.

**Filtering** allows you to narrow the scope of logs that a monitoring rule evaluates. You can filter by log category (Apex, Flow, Process Builder), functional area, specific error types, or any other field available on the log record. This means you can create a monitoring rule that only watches for errors in your critical integration flows, or one that specifically monitors batch job failures.

**Grouping** determines how logs are bucketed for the purpose of evaluation. When you group by a field like the error hash, the monitoring rule treats each unique error type separately when evaluating thresholds. Without grouping, all logs that pass the filter criteria are evaluated together regardless of their specific error type.

For example, you might create a spike rule that groups by functional area. This would allow you to detect when any particular area of your application is experiencing an error spike, while ignoring normal error rates in other areas. The grouping creates separate evaluation contexts within the same rule.

## Time Windows and Thresholds

Monitoring rules operate within configurable time windows. You pick from a preset list — one minute, one hour, eight hours, one day — or enter a custom interval in minutes when none of the presets fits.

Short windows with lower thresholds catch acute problems: something just broke and is breaking repeatedly right now. These enable rapid incident response, potentially catching problems before significant user impact accumulates. A one-minute window with a threshold of 20 indicates an immediate problem worth investigating.

Longer windows with higher thresholds identify sustained problems or gradual degradation — issues that don't look urgent in any given moment but represent a pattern worth addressing. An eight-hour window suits impact rules especially well, since it approximates a working day: "twenty or more users affected during business hours" is a threshold people can reason about.

Windows beyond a day are rarely worth setting. They dilute the point of monitoring, which is to detect quickly; retrospective analysis is better served by reports.

{% hint style="warning" %}
**Threshold Tuning** Setting appropriate thresholds requires understanding your org's baseline behavior. Start with conservative thresholds (higher numbers, longer windows) to avoid alert fatigue, then adjust based on what you learn. It's better to miss marginal events initially than to train your team to ignore alerts because they trigger too frequently.
{% endhint %}

## Use Case Examples

**Critical Flow Monitoring:** You have a flow that handles customer order processing, and any failure directly impacts revenue. You create a user impact rule filtered to that specific flow, triggering when 5 or more different users encounter errors within 10 minutes. This catches problems affecting your customers immediately, allowing rapid response.

**Integration Health Monitoring:** Your org integrates with an external payment processor via Apex callouts. You set up a spike rule filtered to integration logs from that service, triggering when 30 errors occur in a 15-minute window. This detects both your-side problems (bad code in a new deployment) and their-side problems (the payment processor is having issues).

**Batch Job Failure Detection:** You run nightly batch jobs that process large data volumes. You create a spike rule filtered to batch job categories, grouping by the specific batch class name, with a threshold of 10 errors in 5 minutes. This catches jobs that are failing repeatedly, either due to data issues or code problems.

**Platform-Level Problems:** You want to detect when your org is hitting limits or experiencing platform issues. You create a spike rule that monitors for CPU limit exceptions and heap size errors, triggering when 25 such errors occur within 30 minutes. This helps you catch capacity problems before they become critical.

**New Deployment Validation:** After a major release, you temporarily enable a sensitive spike rule with a lower threshold—perhaps 15 errors in 5 minutes across any category. This helps you catch unexpected problems introduced in the release. Once you're confident the release is stable, you can deactivate or adjust this rule.

## Order of Evaluation

Unlike notification rules where evaluation order matters and processing stops after the first match, monitoring rules all evaluate independently. If a log matches the criteria for multiple monitoring rules, all applicable rules will process it. This means you can have overlapping rules—one broad rule watching for general spikes and more specific rules watching particular scenarios—without conflict.

This independence also means the same spike in errors might trigger multiple monitoring events if those errors match criteria for different rules. This behavior is typically desirable, as it allows different teams or processes to be alerted to the same situation from their respective perspectives.

## Cadence Considerations

Monitoring rules should typically remain active in production environments continuously. They represent your real-time safety net for detecting problems. However, in lower environments or during known maintenance windows, you might temporarily deactivate certain rules to avoid noise.

Some organizations create separate monitoring rules for different environments with different thresholds. A UAT environment might have more sensitive rules that catch even minor error increases, while production rules focus on truly anomalous patterns to reduce alert fatigue.

{% hint style="success" %}
**Start Simple, Iterate** Begin with a small number of monitoring rules focused on your most critical processes or known problem areas. As you gain experience with what works, expand your monitoring coverage. Review triggered events regularly to determine if threshold adjustments are needed.
{% endhint %}
