Monitoring & Alerts

A monitor is a health check that watches one field — or every item in a list such as services, disks or installed updates — across all the agents carrying a tag, and fails when the condition you write comes true. When a monitor keeps failing it raises an alert: an incident record you can acknowledge, resolve or delete. This page covers building monitors, the exact meaning of every option, how alerts move through their lifecycle, and how to drive both from the REST API and the PowerShell module.

What a monitor is#

Every monitor is the sum of five things: what it observes (a field from a scan result, a field from agent and inventory data, or every element of a list), a condition that describes the bad state, a severity, an evaluation schedule, and the target tags that decide which machines it runs on. Two behaviours are worth fixing in your mind before you author anything:

Where monitors live#

Monitors are managed under Settings → Monitoring → Monitors (the other Monitoring sub-tab, Tagging Rules, is where you build the tags monitors target). The list shows one row per monitor with its Condition, Target Tags, Severity, Evaluation Interval (minutes), Covered Agents and an Enabled toggle. Use New Monitor to open the editor, the pencil to edit an existing one, and the enabled toggle to switch a monitor on or off without deleting it.

Authoring a monitor#

The editor walks top to bottom. Monitor Name must be unique across the whole system; Description is optional free text. Next you choose what the monitor checks:

For a scalar monitor you then pick a Field, an Operator and a Threshold — for example FreeGB · is less than · 20. The available operators are the familiar comparison set: equals, does not equal, contains, does not contain, starts with, ends with, is greater than, is less than, greater than or equal and less than or equal. The threshold is compared numerically or as text automatically, so 20 compares as a number.

List monitors and correlated conditions#

When you pick a list (services, disks, and so on) two extra controls appear so you can describe the elements of that list precisely:

• When does this monitor fail? — the quantifier, applied across the elements: Any (fail when at least one element matches the whole condition group), None (fail when no element matches — the "X is missing" check), or All (fail when every element matches).
• Combine the conditions with — how the individual conditions combine on each element: AND (all must be true) or OR (any may be true). You can add several conditions with Add condition.

This is what lets you write a monitor that means what you intend. "A service that is both set to Automatic and not Running" is Any element where startupType equals Auto AND status does not equal Running — evaluating the two conditions independently would match almost every machine. Likewise "a required printer is absent" is None element where Name contains "PDF". The editor shows a plain-language read-back of your choices under In plain language so you can confirm the logic before saving.

Severity, schedule and targeting#

The alert lifecycle#

When a monitor fails on an agent for the required number of consecutive evaluations (throttle permitting), it raises an alert. That alert then moves through three states:

Acknowledging and manually resolving an alert are recorded in the audit log with the operator's name. An alert that auto-clears by hysteresis records Auto-cleared on the incident itself and writes no audit row, because no person acted.

Working alerts in the console#

The Alerts page (the 🔔 entry in the main navigation) lists every incident. It opens on the Active (firing + acknowledged) view and can be filtered by severity, state (Active, All, Firing, Acknowledged, Resolved), device and tag; a Clear filters button resets them. Each row shows the severity, monitor, device, the observed value against its threshold, first- and last-seen times and the failure count, and links back to the monitor definition. The badge and the list stay current in real time as conditions change. Per-row actions are:

Running a monitor on demand#

You do not have to wait for the next interval. Forcing a run evaluates the monitor immediately across every agent it currently covers — useful right after you author or change one, or to confirm a fix has taken. A disabled monitor cannot be run on demand: disabling is the deliberate kill switch, and an out-of-band run would resurrect exactly the evaluation you turned off. Each on-demand run is written to the audit log with the operator's name and the number of agents it reached.

REST API#

Everything the console does is available over the API, and an action taken over REST behaves and audits identically to the same action in the UI. Monitors:

# List and read monitors
GET /api/monitors?page=1&pageSize=50
GET /api/monitors/{id}
GET /api/monitors/{id}/targets      # which agents this monitor covers, and why

# Create a "low disk" monitor (condition describes FAILURE: FreeGB < 20)
POST /api/monitors
{
  "name": "Low Disk",
  "scanDefinitionId": "550e8400-e29b-41d4-a716-446655440000",
  "fieldName": "FreeGB",
  "operator": 7,
  "threshold": "20",
  "severity": 2,
  "intervalMinutes": 15,
  "consecutiveFailuresToFire": 3,
  "consecutivePassesToClear": 2,
  "throttleMinutes": 60,
  "targetTags": ["Prod"]
}

# Update (patch semantics: omit a field to leave it unchanged)
PUT /api/monitors/{id}
{ "threshold": "10", "isEnabled": false }

# Force an immediate evaluation across covered agents
POST /api/monitors/{id}/run

DELETE /api/monitors/{id}

The operator value maps to the comparison list (for example 6 = greater than, 7 = less than); severity is 0 Info, 1 Warning, 2 Critical. On update, targetTags is the one field where omitting it (leave unchanged) differs from sending [] (clear all targeting, so the monitor covers nobody). Alerts:

# The open-incidents view the Alerts page opens on (firing + acknowledged)
GET /api/alerts?activeOnly=true

# Filtered/paged history — filters combine with AND, newest first
GET /api/alerts?state=0&severity=2&tag=Prod&page=1&pageSize=50
GET /api/alerts/{id}
GET /api/alerts/summary             # firing / acknowledged / resolved counts

POST /api/alerts/{id}/acknowledge
POST /api/alerts/{id}/resolve
DELETE /api/alerts/{id}             # Admin only

A bare GET /api/alerts returns every state, including resolved history; use activeOnly=true for open incidents, or an explicit state value (0 Firing, 1 Acknowledged, 2 Resolved). See the API Reference.

PowerShell#

The Athena module exposes the same surface as cmdlets:

# Author a scalar monitor
New-AthenaMonitor -Name "Low Disk" `
  -ScanDefinitionId $scan.Id -FieldName "FreeGB" `
  -Operator LessThan -Threshold "20" `
  -Severity Critical -IntervalMinutes 15 `
  -ConsecutiveFailuresToFire 3 -ConsecutivePassesToClear 2 `
  -ThrottleMinutes 60 -TargetTag "Prod"

# A correlated list monitor: any Auto service that is not Running
$c1 = New-AthenaMonitorCondition "startupType" Equals "Auto"
$c2 = New-AthenaMonitorCondition "status" NotEquals "Running"
New-AthenaMonitor -Name "Auto services stopped" `
  -CollectionPath Services -Quantifier Any `
  -ConditionLogic All -Condition $c1,$c2 -TargetTag "Windows"

Get-AthenaMonitor                   # list monitors
Get-AthenaMonitorTarget -Id $id     # which agents it covers
Set-AthenaMonitor -Id $id -Threshold "10" -Enabled $false
Invoke-AthenaMonitor -Id $id        # run now
Remove-AthenaMonitor -Id $id

# Alerts
Get-AthenaAlert -ActiveOnly         # open incidents
Get-AthenaAlertSummary              # firing / acknowledged / resolved counts
Confirm-AthenaAlert -Id $alertId    # acknowledge
Resolve-AthenaAlert -Id $alertId
Remove-AthenaAlert -Id $alertId     # Admin only

Alert retention#

Resolved alerts are pruned automatically so your incident history does not grow without bound. An hourly sweep removes Resolved alerts older than the retention window and records each purge in the audit log. Firing and acknowledged alerts — open incidents — are never purged.

Change it in appsettings.json (or the matching environment variable) and the sweep picks up the new value on its next hourly pass — no restart needed. See Configuration and Database Backup & Maintenance for related retention controls.

Related pages#

• Agent Tags — the tags monitors target, set by hand or by rule.
• Scans — the scan results a monitor's field can observe.
• Inventory — the services, disks, software and updates a list monitor walks.
• Compliance & Baselines — the related model for pass/fail policy across the fleet.
• Audit & SIEM — where acknowledge, resolve, delete, run and purge actions are recorded.