Home › Topics › Writing Custom Checks and Sensors › Checks in PowerShell

Writing Checks in PowerShell


If your servers run Windows, PowerShell is already on every one of them. It already speaks the management interfaces the operating system exposes, and already knows how to reach other machines. That makes it the natural language for a custom check: nothing to install. And the same script works whether it is run by a scheduler, a monitoring system, or you at a console at midnight.


The trouble is that PowerShell is also very forgiving, and forgiving is exactly what a check must not be. Consider a cmdlet that quietly returns nothing, an error that prints red text and carries on, or a remote call with no time limit. Each turns a check into a liar. This guide is the handful of patterns that keep PowerShell honest. It covers how to ask the common questions and how to say the answer in a form a monitor can parse. It also covers how to make sure the script always finishes and never claims health it did not measure.


This is a patterns guide, not a tour of one script. For a complete probe built end to end, see PowerShell as a Monitoring Probe. For the rules every check obeys regardless of language, start with The Anatomy of a Custom Check.


In this guide

  • The shape of a PowerShell check
  • The patterns: asking the common questions
  • Output formatting: exit codes or JSON
  • Error handling and timeouts
  • Credentials from a protected store
  • Scheduling: Task Scheduler or the monitor
  • A complete small check: service state
  • Patterns, cmdlet families, and gotchas
  • Where to go next

The shape of a PowerShell check


Every check in this guide has the same skeleton. A param block declares the inputs, with the target mandatory and everything else defaulted. A tiny table maps state names to exit codes. A state variable starts life as UNKNOWN so nothing short of a real measurement can turn it into OK. And one helper prints the result line and exits with the matching code.


[CmdletBinding()]
param(
    [Parameter(Mandatory = $true)] [string] $ComputerName,
    [int] $WarnAbove = 80,
    [int] $CritAbove = 95,
    [int] $TimeoutSeconds = 10
)

$States  = @{ OK = 0; WARNING = 1; CRITICAL = 2; UNKNOWN = 3 }
$state   = 'UNKNOWN'                    # fail closed
$message = 'check did not complete'
$value   = $null

function Finish {
    param([string] $State, [string] $Message, $Value)
    $line = "$State - $Message"
    if ($null -ne $Value) { $line += " | value=$Value" }
    Write-Output $line                  # the ONLY thing written to stdout
    exit $States[$State]
}

Two habits are worth adopting from the first line. Declare parameter types so a typo in a threshold fails loudly at start-up rather than comparing text to numbers later. And use Write-Output for the result only. Progress and debugging go to Write-Verbose or a log file, because the monitor will parse every line that lands on standard output.


The patterns: asking the common questions


Each pattern below is a fragment that slots into the skeleton above. Each ends by setting $state, $message, and $value, and each carries its own time limit.


Service and process state via CIM

CIM (Common Information Model) is the standard way to ask Windows about itself, and WMI is the older name for the same idea. Get-CimInstance is the modern cmdlet and accepts a timeout, which the older Get-WmiObject does not. What CIM and WMI can tell you about a machine is covered in WMI and CIM for Network Data. Here we need one class.


$svc = Get-CimInstance -ClassName Win32_Service -Filter "Name='$ServiceName'" `
       -ComputerName $ComputerName -OperationTimeoutSec $TimeoutSeconds -ErrorAction Stop

if ($null -eq $svc)                { $message = "service '$ServiceName' not found" }   # stays UNKNOWN
elseif ($svc.State -eq 'Running')  { $state = 'OK';       $message = "$ServiceName running";  $value = 1 }
else                               { $state = 'CRITICAL'; $message = "$ServiceName is $($svc.State)"; $value = 0 }

Notice the three-way split. A missing service is not a stopped one: if you typed the name wrong, the honest answer is UNKNOWN, not "the service is down." Processes work the same way with Win32_Process; count the results against how many instances you expect.


Disk space

$disk = Get-CimInstance -ClassName Win32_LogicalDisk -Filter "DeviceID='$Drive'" `
        -ComputerName $ComputerName -OperationTimeoutSec $TimeoutSeconds -ErrorAction Stop
$freeGb  = [math]::Round($disk.FreeSpace / 1GB, 1)
$freePct = [math]::Round(100 * $disk.FreeSpace / $disk.Size, 1)
$value   = $freeGb
if     ($freeGb -lt $CritBelowGb) { $state = 'CRITICAL' }
elseif ($freeGb -lt $WarnBelowGb) { $state = 'WARNING' }
else                              { $state = 'OK' }
$message = "$freeGb GB free ($freePct%) on $Drive"

Values arrive in bytes; PowerShell's 1GB constant makes the conversion readable. Volumes mounted in folders rather than drive letters do not appear in Win32_LogicalDisk; query Win32_Volume for those. Offering both an absolute and a percentage threshold is worth two extra parameters: a huge volume and a small system disk disagree about "nearly full."


Performance counters

$samples = Get-Counter -Counter '\Processor(_Total)\% Processor Time' `
           -ComputerName $ComputerName -SampleInterval 1 -MaxSamples 3 -ErrorAction Stop
$value = [math]::Round(($samples.CounterSamples | Measure-Object -Property CookedValue -Average).Average, 1)

Two gotchas. Get-Counter has no timeout parameter and reaches remote machines over a different path than CIM, so it can hang where CIM would not. Wrap it in a job as shown later. And a single sample of a rate counter is meaningless, which is why the fragment averages three. To stay on the CIM path, the Win32_PerfFormattedData_* classes expose the same counters, pre-cooked, with a timeout.


A TCP port, with a real timeout

"Is anything listening on port 8443?" is the simplest network question there is. The obvious cmdlet, Test-NetConnection, is fine at a console but the wrong tool inside a check. It pings first and has no timeout parameter. Against a silently filtered port it can sit for a long time. Use the socket class directly and wait on the connection yourself.


$client = New-Object System.Net.Sockets.TcpClient
try {
    $async = $client.BeginConnect($ComputerName, $Port, $null, $null)
    if ($async.AsyncWaitHandle.WaitOne($TimeoutSeconds * 1000)) {
        $client.EndConnect($async)          # throws if the connection was refused
        $state = 'OK'; $message = "port $Port open"
    } else {
        $state = 'CRITICAL'; $message = "no answer on port $Port within $TimeoutSeconds s"
    }
}
catch [System.Net.Sockets.SocketException] {
    $code = $_.Exception.SocketErrorCode
    if ($code -eq 'ConnectionRefused') { $state = 'CRITICAL'; $message = "port $Port refused" }
    else                               { $message = "could not ask: $code" }   # e.g. HostNotFound: UNKNOWN
}
finally { $client.Dispose() }

This fragment is a small lesson in CRITICAL versus UNKNOWN. A refused connection and a silent timeout are the target answering badly: CRITICAL. A name that does not resolve means the question was never asked: the state stays UNKNOWN.


HTTP status and response time

$sw = [System.Diagnostics.Stopwatch]::StartNew()
try {
    $resp = Invoke-WebRequest -Uri $Url -TimeoutSec $TimeoutSeconds -UseBasicParsing -ErrorAction Stop
    $status = [int] $resp.StatusCode
}
catch [System.Net.WebException] {
    if ($_.Exception.Response) { $status = [int] $_.Exception.Response.StatusCode }   # 4xx / 5xx arrive here
    else { $message = "no HTTP response: $($_.Exception.Status)" }                  # timeout, DNS, refused
}
$value = $sw.ElapsedMilliseconds
if ($status) {
    if     ($status -ne $ExpectedStatus)  { $state = 'CRITICAL'; $message = "status $status, expected $ExpectedStatus" }
    elseif ($value -gt $CritAboveMs)      { $state = 'CRITICAL'; $message = "status $status but $value ms" }
    elseif ($value -gt $WarnAboveMs)      { $state = 'WARNING';  $message = "status $status, slow at $value ms" }
    else                                  { $state = 'OK';       $message = "status $status in $value ms" }
}

The trap is that Invoke-WebRequest treats any status outside the success range as an error and throws. So a page returning 503 lands in the catch block, where the status must be fished out of the exception. If a service is only healthy when its body says so, add a check on $resp.Content. A 200 from a load balancer's maintenance page is a classic false green.


Certificate expiry on a listener

# $tcp is a TcpClient connected with the port pattern above
$tcp.ReceiveTimeout = $TimeoutSeconds * 1000
$ssl = New-Object System.Net.Security.SslStream($tcp.GetStream(), $false, ({ $true }))   # accept any cert: we only READ it
$ssl.AuthenticateAsClient($ComputerName)          # the name matters: it selects the certificate on shared hosts
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($ssl.RemoteCertificate)
$value = [int] ($cert.NotAfter - (Get-Date)).TotalDays
$ssl.Dispose(); $tcp.Dispose()
if     ($value -lt $CritBelowDays) { $state = 'CRITICAL' }
elseif ($value -lt $WarnBelowDays) { $state = 'WARNING' }
else                               { $state = 'OK' }
$message = "certificate for $($cert.Subject) expires in $value days"

The validation callback that returns $true looks alarming but is necessary. An already-expired certificate would otherwise make the handshake fail before you could read its date. The callback is safe because the check sends no data and trusts nothing. What to do with the number — thresholds, renewals, the certificates hiding on internal listeners — is the subject of Monitoring Certificate Expiry.


DNS resolution

$answer = Resolve-DnsName -Name $Name -Server $DnsServer -Type A -DnsOnly -NoHostsFile -ErrorAction Stop
$ips = ($answer | Where-Object Type -eq 'A').IPAddress
if (-not $ips)                                { $state = 'CRITICAL'; $message = "$Name has no A record on $DnsServer" }
elseif ($ExpectedIp -and $ips -notcontains $ExpectedIp) { $state = 'CRITICAL'; $message = "$Name resolved to $ips, expected $ExpectedIp" }
else                                          { $state = 'OK'; $message = "$Name resolves to $ips" }

Always pass -Server; without it you are testing the collector's own resolver and its cache, not the DNS server you meant. -DnsOnly and -NoHostsFile stop Windows helpfully answering from other sources. No timeout parameter here either, so it is another candidate for the job wrapper below.


Output formatting: exit codes or JSON


Monitoring products differ in how they want a result delivered; check your product's documentation. Two shapes cover most of them. The first is what the skeleton already produces. It is one line of text with the state first and an optional value after a vertical bar. The result also includes an exit code of 0, 1, 2, or 3. The second is a small JSON object, easier when a check has several values or when the monitor reads results from a file or an HTTP push:


$result = [ordered]@{
    state   = $state
    value   = $value
    unit    = 'ms'
    message = $message
}
$result | ConvertTo-Json -Compress
exit $States[$state]

Whichever you use, keep the exit code: it costs nothing, and a scheduler, a wrapper, or a human can tell what happened without parsing anything. And keep the message short; it becomes the alert subject line.


Error handling and timeouts


PowerShell's default reaction to a failing cmdlet is to write an error and keep going. In a check that is catastrophic. The query fails, and the variable that should hold the answer stays empty. The comparison that follows produces a state with no connection to reality. Two settings fix it. Put -ErrorAction Stop on every cmdlet that matters, so failures become exceptions. Wrap the measuring code in try/catch so every exception ends in UNKNOWN with a message rather than red text on standard output.


try {
    # ... the measuring pattern goes here ...
}
catch [System.UnauthorizedAccessException] { $message = "access denied on $ComputerName" }
catch { $message = "unexpected: $($_.Exception.GetType().Name)" }   # state stays UNKNOWN
finally { <# close sessions, write the log line #> }
Finish $state $message $value

Timeouts are the second half. Some cmdlets accept one (-OperationTimeoutSec on CIM, -TimeoutSec on web requests); the socket pattern builds its own. For cmdlets with none — performance counters, DNS, most third-party modules — the simplest reliable fence is a background job. Run the slow call in a job and wait with a limit. If the limit passes, kill the job and report UNKNOWN.


$job = Start-Job -ArgumentList $ComputerName -ScriptBlock {
    param($c)
    Get-Counter -Counter '\Memory\Available MBytes' -ComputerName $c -ErrorAction Stop
}
if (Wait-Job $job -Timeout $TimeoutSeconds) {
    try   { $data = Receive-Job $job -ErrorAction Stop }
    catch { $message = "counter query failed: $($_.Exception.GetType().Name)" }
} else {
    $message = "counter query timed out after $TimeoutSeconds s"
}
Remove-Job $job -Force        # always, even on success

A job is a separate PowerShell process, with two consequences. It takes a moment to start, so do not use it for something that already has a timeout. And it cannot see your variables: everything it needs must be passed through -ArgumentList, credentials included. Faster asynchronous alternatives exist (runspaces, thread jobs), but the job pattern is the one a colleague can read at three in the morning.


Tip: Test every timeout with a stopwatch, not with faith. Point the check at an address that drops packets silently (an unused address on a routed subnet) and time how long it takes to say UNKNOWN. Session setup in some cmdlets has its own connection timeout that runs before your operation timeout starts, and the total can be longer than you assumed.


Credentials from a protected store


A check that reaches another machine often needs an account. And its password must not live in the script, in the scheduled task's arguments, or in a check definition in clear text. PowerShell gives you three reasonable homes for it.


  • An environment variable set by whatever launches the check. The script reads $env:CHECK_PASSWORD, builds a credential object, and never writes it anywhere.
  • A credential file encrypted for one account on one machine. Run Get-Credential | Export-Clixml -Path C:\checks\monitor-ro.cred once, interactively, as the account that will run the check. The operating system's data protection encrypts it so that other users and other machines cannot read it. The check loads it with Import-Clixml. Simple, robust, and the reason the scheduled task must run as that same account.
  • A secrets-management module. PowerShell has a module family that fronts a local vault or an enterprise secret store. The check asks for a secret by name and gets a credential object back. Best when several collectors share credentials that rotate.

$cred = if ($CredentialFile) { Import-Clixml -Path $CredentialFile }
        elseif ($env:CHECK_PASSWORD) {
            $sec = ConvertTo-SecureString $env:CHECK_PASSWORD -AsPlainText -Force
            New-Object System.Management.Automation.PSCredential($env:CHECK_USER, $sec)
        }
$session = New-CimSession -ComputerName $ComputerName -Credential $cred -OperationTimeoutSec $TimeoutSeconds

Whatever the store, the account should be dedicated and least-privilege: a member of the remote machine's remote-management groups rather than an administrator. A read-only check running as a domain administrator is an accident waiting for a script bug.


Scheduling: Task Scheduler or the monitor


There are two ways a check gets run, and they lead to different designs. In the first, the monitoring system invokes the script. It owns the schedule, passes target and thresholds as parameters, captures the output and exit code, and stores the result. That is the cleanest arrangement, because one script serves every target and the monitor already knows how to alert on it. Whether your product can invoke an external script, and what format it expects back, is a product-documentation question.


In the second, Task Scheduler runs the script on a collector host. The script delivers its result by another route. That can be a push to an API, a line in a file the monitor reads, or a value the monitor collects afterwards. Going this way, a few settings on the task matter as much as the script:


  1. Run it as the dedicated least-privilege account, with "run whether user is logged on or not."
  2. Launch it as powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File C:\checks\Check-Service.ps1 -ComputerName srv01 -ServiceName Spooler. No profile means no surprises from someone's console customisations; non-interactive means it can never sit waiting for a prompt.
  3. Set "stop the task if it runs longer than" to a little more than the script's own timeout. Do not allow a new instance while one is running.
  4. Make the task's own health visible. A task that stops firing is silent, and silence looks like health; the fix is a heartbeat, described in Heartbeats and Dead-Man Switches.

A complete small check: service state


Here is the skeleton and the service pattern assembled into one file. It has a timeout, proper states, a credential by reference, a log line, and one line of output. It is deliberately boring.


<#  Check-ServiceState.ps1  -  Is ONE Windows service running on ONE host?
    Exit codes: 0 OK, 1 WARNING, 2 CRITICAL, 3 UNKNOWN.  Read-only: it never starts or stops anything.  #>
[CmdletBinding()]
param(
    [Parameter(Mandatory = $true)] [string] $ComputerName,
    [Parameter(Mandatory = $true)] [string] $ServiceName,
    [int]    $TimeoutSeconds = 10,
    [string] $CredentialFile = '',                       # optional Export-Clixml file
    [string] $LogPath = "$env:ProgramData\checks\service-check.log"
)
$States  = @{ OK = 0; WARNING = 1; CRITICAL = 2; UNKNOWN = 3 }
$state   = 'UNKNOWN'; $message = 'check did not complete'; $value = $null
$session = $null; $started = Get-Date

try {
    $opts = @{ ComputerName = $ComputerName; OperationTimeoutSec = $TimeoutSeconds; ErrorAction = 'Stop' }
    if ($CredentialFile) { $opts.Credential = Import-Clixml -Path $CredentialFile }
    $session = New-CimSession @opts
    $svc = Get-CimInstance -CimSession $session -ClassName Win32_Service `
           -Filter "Name='$ServiceName'" -OperationTimeoutSec $TimeoutSeconds -ErrorAction Stop

    if ($null -eq $svc) {
        $message = "service '$ServiceName' does not exist on $ComputerName"       # UNKNOWN: bad question
    } elseif ($svc.State -eq 'Running') {
        $state = 'OK';       $value = 1; $message = "$ServiceName running (start mode $($svc.StartMode))"
    } elseif ($svc.StartMode -eq 'Disabled') {
        $state = 'WARNING';  $value = 0; $message = "$ServiceName is $($svc.State) and disabled"
    } else {
        $state = 'CRITICAL'; $value = 0; $message = "$ServiceName is $($svc.State)"
    }
}
catch {
    $message = "could not query $ComputerName: $($_.Exception.GetType().Name)"    # stays UNKNOWN
}
finally {
    if ($session) { Remove-CimSession $session }
    $elapsed = [int] ((Get-Date) - $started).TotalMilliseconds
    "$(Get-Date -Format s) $ComputerName $ServiceName $state ${elapsed}ms" | Out-File -Append -FilePath $LogPath
}
Write-Output "$state - $message | running=$value elapsed_ms=$elapsed"
exit $States[$state]

Read it against the contract. Target and question are mandatory parameters; timeout and credential have defaults. The state starts as UNKNOWN and only three specific measurements can change it. A stopped-but-disabled service is WARNING rather than CRITICAL because someone chose that state on purpose. Every failure path lands in the catch block with a message and leaves the state alone. The session is always closed, a log line always written, and the last two lines are the only output. To make it a disk or port check, swap the middle and keep everything else.


Patterns, cmdlet families, and gotchas


QuestionCmdlet familyGotcha
Service or process stateGet-CimInstance Win32_Service, Win32_ProcessMissing is UNKNOWN, stopped is CRITICAL; Get-Service has no timeout
Disk spaceWin32_LogicalDisk, Win32_Volume for mount pointsValues are bytes; offer both GB and percent thresholds
Performance countersGet-Counter, or Win32_PerfFormattedData_* via CIMNo timeout on Get-Counter; average several samples of rate counters
TCP portTcpClient.BeginConnect + WaitOneTest-NetConnection pings first and cannot be given a timeout
HTTP status and timingInvoke-WebRequest -TimeoutSecNon-success statuses throw; read them from the exception; a 200 maintenance page is a false green
Certificate expirySslStream over TcpClientAccept any certificate in the callback or expired ones cannot be read
DNS resolutionResolve-DnsName -Server -DnsOnly -NoHostsFileWithout -Server you test the local cache; no timeout parameter
Anything without a timeoutStart-Job, Wait-Job -Timeout, Remove-Job -ForceJobs are new processes: slow to start and blind to your variables
Any failure-ErrorAction Stop + try/catchWithout it errors print and the script continues into a wrong state

Where to go next


A good PowerShell check has a param block with typed inputs and a state that starts at UNKNOWN. It has one measuring pattern with a time limit, -ErrorAction Stop and a catch that reports rather than crashes. It also has a credential loaded by reference, one line of output, and an exit code. The patterns above cover services, disks, counters, ports, web endpoints, certificates, and DNS. Nearly every other Windows question is a variation on one of them.


When the target or the collector is not Windows, the same contract in Python is covered in Writing Checks in Python. For choosing whether to ask over SNMP, SSH, or an API, see SSH, SNMP, and API Collection Patterns. The full set lives under Writing Custom Checks and Sensors.


Put this into practice with SysPeep Monitor

The questions in this guide are everyday work for SysPeep Monitor's built-in WMI and SNMP collectors. Is the service running? Is the disk filling? Is the port answering? Thresholds, dependencies, and alert rules keep the noise down, and dashboards show it all from one console. Where a scripted check is still the right answer, check the product documentation for how it accepts custom results. The free trial runs on a single Windows machine.

Download Free TrialLearn About SysPeep