Monitoring Rules
Define staleness thresholds with monitoring rules to detect when deployed software falls behind upstream releases.
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.0and7.1.2are the same minor (7.1), so they count as one. - Major version bumps count. A jump from
7.xto8.0counts as a minor release because8.0is a newmajor.minorcombination. - Only actual releases matter. If a project skips version numbers (e.g., goes from
2.3to2.7), only the versions that actually appear in the release history are counted. - Prereleases are excluded when
stable_onlyis 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 |
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
Navigate to Rules in the sidebar.
Click Create Rule.
Fill in the form:
Field Description Name A descriptive label, e.g., “Critical Update Window” Type days_behind,majors_behind, orminors_behindModerate 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 Click Save.
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.
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.