Source: https://docs.planekeeper.com/guides/rules/
Site: Planekeeper Docs
Title: Monitoring Rules
Description: Define staleness thresholds with monitoring rules to detect when deployed software falls behind upstream releases.

***

# Monitoring Rules


Monitoring rules define the thresholds that determine when a deployed version is unacceptably behind. Each rule specifies a measurement type, threshold values for three severity tiers, and optional filtering for stable releases only.

## What rules measure

A rule answers one question: **how far behind is the deployed version compared to what is available upstream?** Planekeeper supports three ways to measure that distance.

### Days behind

Measures the age of the deployed version in calendar days. Use this when you care about how old a release is, regardless of how many versions have shipped since.

- A version released 90 days ago is 90 days behind.
- If the deployed version does not appear in the upstream release history, the rule treats this as critical.

### Majors behind

Measures the gap in major version numbers between the deployed version and the latest release. Use this for software that follows semantic versioning and ships breaking changes in major releases.

- Deployed on v1.x, latest is v3.x = 2 majors behind.
- Only the major component of the version number is compared.

### Minors behind

Counts the number of **unique minor releases** between the deployed version and the latest release. Use this to track how far behind you are on incremental releases.

Unlike `majors_behind` which simply compares major version numbers, `minors_behind` counts actual releases — this means major version bumps are included in the count as they represent new minor releases too.

#### How it's calculated

When full release history is available (the default), Planekeeper counts every unique `major.minor` combination that falls between your deployed version (exclusive) and the latest version (inclusive).

**Example:** Your deployed version is `7.0.3` and the upstream has released:

| Release | major.minor | Counted? |
|---------|-------------|----------|
| `7.0.3` | `7.0` | No — this is your current version |
| `7.1.0` | `7.1` | Yes |
| `7.1.2` | `7.1` | No — `7.1` already counted |
| `7.2.0` | `7.2` | Yes |
| `8.0.0` | `8.0` | Yes |
| `8.1.0` | `8.1` | Yes |

**Result: 4 minor releases behind** (`7.1`, `7.2`, `8.0`, `8.1`)

Key points:

- **Patch releases don't count.** `7.1.0` and `7.1.2` are the same minor (`7.1`), so they count as one.
- **Major version bumps count.** A jump from `7.x` to `8.0` counts as a minor release because `8.0` is a new `major.minor` combination.
- **Only actual releases matter.** If a project skips version numbers (e.g., goes from `2.3` to `2.7`), only the versions that actually appear in the release history are counted.
- **Prereleases are excluded** when `stable_only` is enabled.

When release history is incomplete, Planekeeper falls back to a formula-based estimate that uses version number arithmetic.

## Severity tiers

Every rule defines three escalating thresholds: **moderate**, **high**, and **critical**. The thresholds must be in ascending order.

When a rule evaluates, it compares the calculated behind-by value against these thresholds, highest first:

| Condition | Resulting severity |
|---|---|
| Behind-by >= critical threshold | Critical |
| Behind-by >= high threshold | High |
| Behind-by >= moderate threshold | Moderate |
| Below all thresholds | No violation |

> **success:** 
**Recommended starting thresholds**

For **days behind**: moderate = 90, high = 180, critical = 365. This gives teams a quarterly nudge, a six-month warning, and a yearly hard stop.

For **majors behind**: moderate = 1, high = 2, critical = 3. Most projects can tolerate being one major behind, but three usually signals a migration risk.

For **minors behind**: moderate = 3, high = 6, critical = 10. Adjust based on how frequently the upstream project ships minor releases.


## Create a rule

1. Navigate to **Rules** in the sidebar.
2. Click **Create Rule**.
3. Fill in the form:

    | Field | Description |
    |---|---|
    | **Name** | A descriptive label, e.g., "Critical Update Window" |
    | **Type** | `days_behind`, `majors_behind`, or `minors_behind` |
    | **Moderate threshold** | The value that triggers a moderate alert |
    | **High threshold** | The value that triggers a high alert |
    | **Critical threshold** | The value that triggers a critical alert |
    | **Stable only** | When checked, ignore prerelease versions when finding the latest upstream release |

4. Click **Save**.

> **info:** 
The "stable only" option filters out versions tagged as alpha, beta, RC, dev, snapshot, canary, nightly, or pre. Enable this if your upstream project publishes prerelease tags and you only want to compare against production-ready versions.


## How evaluation works

You do not trigger rule evaluation manually. Planekeeper evaluates rules automatically when:

- A **scrape job** completes and discovers a version.
- A **gather job** completes and fetches new upstream releases.
- An **alert config** is created, updated, or toggled on.

When any of these events occur, every active alert config in the organization is re-evaluated against its linked rule. If the deployed version violates a threshold, an alert is created or updated. If it no longer violates, the existing alert is resolved.

## Evaluate all rules

Click **Evaluate All** at the top of the Rules page to trigger a full re-evaluation of every active alert config in the organization. This is useful after bulk-editing rules or alert configs, or when you want to immediately refresh all alert states without waiting for the next job completion event.

## Toggle a rule on or off

Each rule has an active/inactive toggle. Click the toggle badge on the rules list to switch the state.

- **Active** rules participate in evaluation. Alert configs that reference them will generate alerts when thresholds are exceeded.
- **Inactive** rules are skipped during evaluation. Existing alerts from these rules remain in their current state but will not be updated.

> **warning:** 
Deactivating a rule does not automatically resolve existing alerts created by that rule. Those alerts stay active until the underlying version gap is addressed or you acknowledge them manually.


## Common patterns

**Tiered monitoring for the same software**: Create multiple rules with different types and thresholds, then link them to the same scrape and gather jobs through separate alert configs. For example, track both days behind (for absolute staleness) and majors behind (for breaking-change risk) on the same deployment.

**Organization-wide standards**: Create rules that represent your organization's update policy, then reuse them across many alert configs. A single "90/180/365 days behind" rule can apply to dozens of monitored applications.

**Gradual rollout**: Start with generous thresholds and tighten them as your team builds confidence in the update workflow. Increase thresholds gradually rather than setting strict values that generate noise.