Before you begin
- Atlas Reach enabled for the tenant, with the Atlas Reach agent installed and approved on your devices
- An Atlas administrator account to create, edit or delete checks
- The reach.script permission to create remediation rules, and script running turned on for your deployment (see Automated remediation below)
Opening the Checks tab
Open Atlas Reach and click the Checks tab. Three tiles summarise your position: Check policies, Devices with a failing check, and Failing checks. Below them are the Alert notification policy card, the Check policies table (every check and the scope it applies to), the Device check status table (each device, how many checks it has, how many are failing and when it was last evaluated) and the Automated remediation panel. Both tables can be exported.
A device's own Checks tab, on its device page, shows the same checks as they apply to that one device, and lets an administrator add a device-scoped check there.
Check types
Checks come in two families. Metric checks are judged on the server from the telemetry every agent already streams, so they need nothing extra on the device. On-device checks are run by the agent on its own interval and reported back.
- Metric checks: CPU usage (%), Memory usage (%), Disk free space (%, on the system volume or a drive or mount point you name), RemoteFX round-trip time (ms) and CPU temperature (°C).
- Service running: the target is the service name, for example frxsvc or Spooler on Windows, or a systemd unit or launchd label on Linux and macOS.
- Ping: the target is a host name or IP address; the threshold is the round-trip time in ms.
- Event log (Windows only): the target is Log/EventId, for example System/7034, and the check fails when more than the threshold number of events appear.
- Script: the target is a script from your Scripts library. Exit code 0 passes and anything else fails. You can also store the output in a device custom field and judge the output itself, which turns the script into a custom check (see Check a Device Setting with a PowerShell Script).
- HTTP endpoint: the device requests a URL. A 4xx or 5xx status, a TLS error or no answer fails.
- TCP port open: a host:port the device should be able to connect to, for example sql01:1433.
- SSL certificate expiry: a host (port 443 unless you give one). The check fails when the certificate has fewer days left than the threshold; the default is 14 days.
Metric checks fail when the value is above the threshold, except Disk free space, which fails when it drops below. Where a check needs a target, the editor shows the expected format under the field.
Scopes and the built-in checks
Devices inherit checks from the widest scope to the narrowest: Global → Tenant → Host pool → Device. Atlas ships three built-in checks at the Global (built-in) scope for every device that reports a host pool: Disk free below 15%, FSLogix service running, and RemoteFX RTT above 150 ms. A check at a narrower scope with the same type and name replaces the inherited one for the devices in that scope.
- To change a built-in for some devices, click Override on its row, choose Tenant, Host pool or Device, and set the new threshold. The original keeps applying everywhere else.
- To switch an inherited check off for a scope, create the override and turn its Enabled switch off. A disabled check at a narrower scope switches the inherited check off there.
- A new check of your own can be scoped to the whole tenant, one host pool or one device. From a device's own Checks tab, the scope is locked to that device.
Check settings
Click New check, or Edit on a row, to open the editor. Give the check a name, choose its type and severity, fill in the target where the type needs one, and set when it fails.
- Fail when: above or below the threshold, in the unit shown for the type.
- Consecutive samples: how many evaluations in a row must breach before the check counts as failed, from 1 to 60. The built-in disk check uses 3 and the RTT check uses 5, so a brief spike does not alert.
- Interval: how often the check is evaluated, from 30 seconds to 24 hours. The default is 60 seconds for metric checks and 300 seconds (5 minutes) for on-device checks.
- Cooldown between alerts: how long after a failure alert Atlas waits before alerting again for the same check on the same device if it is still failing. The default is 900 seconds (15 minutes).
- Severity: info, notice, warning, error or critical. The default is warning.
A device can carry up to 64 checks after inheritance is resolved. A check's name can be up to 120 characters. Deleting a check removes its per-device state; any alert it had already raised stays in the history.
Alerts from checks
Each check on each device raises Atlas Reach check failed once when it goes from passing to failing, and Atlas Reach check recovered once when it passes again. Both land in the Atlas Reach notification category, so they follow the channels and rules you set up on Settings → Notifications, and both appear in the bell and in the device's history.
- The Alert notification policy card at the top of the Checks tab sets the lowest check severity that is sent out over email, webhooks or SMS. A failing check below that level is still recorded in the device history and the bell; it just does not page anyone. The default is every severity. A host pool can tighten this on its own policy.
- A check that could not be evaluated, for example because the interpreter is missing or the type is not supported on that platform, shows as an error rather than a failure and does not alert.
- The Device check status table shows each device's failing checks with the detail the agent reported, such as which service was not running.
Automated remediation
The Automated remediation panel at the bottom of the Checks tab lists your remediation rules. A rule binds a check to a script: when the check fails (or recovers), Atlas runs the script on the affected device automatically, with the same gating as a run an operator starts, and records the run in the device's run history and the audit log, linked to the alert that triggered it.
Remediation scripts only run when script running is turned on for your Atlas AVD deployment, and that switch is off on every new deployment. Until an Azure administrator turns it on, rules are saved and evaluated but no script is ever dispatched, so automated remediation is effectively off by default. See Before you start: turn on script running in Run Scripts and Schedule Automation.
Create a remediation rule
Click New rule in the Automated remediation panel.
- Give the rule a name, for example Restart the print spooler.
- Pick the check it remediates and the trigger: When the check fails or When the check recovers.
- Choose the action's script. Library script: enter the script's id from your Scripts library and, optionally, pin a version; otherwise the current version runs. Ad-hoc script: pick the interpreter and type the script, up to 256 KB.
- Choose the scope: Whole tenant, One host pool or One device. Like checks, a narrower rule with the same check, trigger and name replaces the broader one.
- Set the guardrails (below), decide whether to start in Dry run, and click Save rule.
Guardrails, dry run and escalation
Every rule is bounded on the server, so a flapping check cannot turn into a script running in a loop.
- Cooldown: the same rule does not run again on the same device within this many seconds of its last run. The default is 600 seconds (10 minutes).
- Max attempts and Window: at most this many runs per rolling window. The default is 3 attempts per 3,600-second (1-hour) window; once reached, further triggers are recorded as skipped until the window rolls on. The window can be from 1 minute to 7 days.
- Dry run: the rule records what would have run, and runs nothing. Use it to see how often a rule would fire before you let it act. Dry-run rules show a Dry run badge in the table.
- Escalate after: once this many runs have happened in the window without the check recovering, Atlas raises an Atlas Reach remediation escalated alert at the Escalation severity you choose (critical by default) so a person is paged. 0 turns escalation off, which is the default.
- Up to 8 enabled rules can bind to one check and trigger at a scope.
The Guardrails column summarises each rule as attempts per window and cooldown, for example 3×/60m, 10m cooldown. Each automatic run, skip, dry run and escalation is listed on the device page's Remediation history panel.
Permissions
- Creating, editing, overriding and deleting checks is admin-only. Other roles see the Checks tab read-only.
- Creating and editing remediation rules needs reach.script, because a rule runs a script. The New rule button and the Edit and Delete actions only appear for a user who holds it.
- Viewing checks, device status and remediation rules needs reach.view.
- Library scripts need the Scripts feature, which is included from the Starter plan. Ad-hoc scripts do not.
Troubleshooting
- A rule never runs anything, and its history shows nothing: script running is off for the deployment. Turn it on as described in Run Scripts and Schedule Automation.
- A rule's runs show as skipped: its cooldown or max attempts guardrail suppressed them. Raise the limits or lengthen the window if the skips are unwanted.
- A check shows as error instead of failing or passing: the agent could not evaluate it. Event log checks only run on Windows, script checks need the interpreter on the device, and a service check needs the exact service name.
- A check never leaves unknown: it has not been evaluated yet, or the device's telemetry is too stale to judge. Check that the device is online and its agent is approved.
- You cannot see New check or New rule: your role is not an administrator, or does not hold reach.script. Ask an administrator.
- Nobody was notified about a failing check: its severity is below the Alert notification policy minimum for the tenant or host pool, or the Atlas Reach category is off in Settings → Notifications.