A Ping Monitor That Logs Every Outage to CSV

<#
.SYNOPSIS
    Pings one or more hosts on an interval, logs every reply to CSV, and summarizes the outages when you stop it.
.DESCRIPTION
    Sends one ICMP echo to each target every -IntervalSeconds and appends a row per ping to a CSV:
    timestamp, target, Up or Down, latency, and whether the target just changed state. A target is
    only marked down after -DownAfter misses in a row, so one dropped packet on Wi-Fi doesn't count
    as an outage. Up/down changes are also written to the console as they happen.
    Runs until -Duration is up, or until you press Ctrl+C or Q. Either way it finishes cleanly and
    returns one summary object per target, including every outage with its start, end and length.
.PARAMETER ComputerName
    Host names or IP addresses to watch.
.PARAMETER IntervalSeconds
    Seconds between rounds of pings. Default: 5.
.PARAMETER Duration
    How long to run, as a timespan ('00:30:00', '8:00:00' or New-TimeSpan -Hours 8). Default: until stopped.
.PARAMETER TimeoutMs
    How long to wait for each reply, in milliseconds. Default: 1000.
.PARAMETER DownAfter
    Consecutive misses before a target counts as down. Default: 2.
.PARAMETER LogPath
    CSV file to append to. Default: PingLog-<date>-<time>.csv in the current folder.
.EXAMPLE
    .\Watch-PingTarget.ps1 -ComputerName 192.0.2.10, NAS01 -Duration 8:00:00
.EXAMPLE
    .\Watch-PingTarget.ps1 -ComputerName gateway.contoso.com -IntervalSeconds 1 -DownAfter 3 -LogPath .\gateway.csv
#>
[CmdletBinding()]
param(
    [Parameter(Mandatory, Position = 0, ValueFromPipeline, ValueFromPipelineByPropertyName)]
    [Alias('CN', 'Target', 'IPAddress')]
    [ValidateNotNullOrEmpty()]
    [string[]]$ComputerName,

    [ValidateRange(1, 3600)]
    [int]$IntervalSeconds = 5,

    [timespan]$Duration = [timespan]::Zero,

    [ValidateRange(100, 60000)]
    [int]$TimeoutMs = 1000,

    [ValidateRange(1, 100)]
    [int]$DownAfter = 2,

    [string]$LogPath = (Join-Path (Get-Location) ('PingLog-{0:yyyyMMdd-HHmmss}.csv' -f (Get-Date)))
)

begin { $targets = [System.Collections.Generic.List[string]]::new() }

process { foreach ($name in $ComputerName) { if (-not $targets.Contains($name)) { $targets.Add($name) } } }

end {
    $LogPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($LogPath)
    $logDir = Split-Path -Path $LogPath -Parent
    if ($logDir -and -not (Test-Path -LiteralPath $logDir)) { $null = New-Item -ItemType Directory -Path $logDir -Force }

    # Per-target running state.
    $state = [ordered]@{}
    foreach ($t in $targets) {
        $state[$t] = [pscustomobject]@{
            Name = $t; IsDown = $false; Misses = 0; FirstMiss = $null; Sent = 0; Received = 0
            TotalMs = 0L; MaxMs = 0L; Outages = [System.Collections.Generic.List[object]]::new()
        }
    }

    # Ctrl+C normally kills the script mid-loop. Treating it as a keypress lets us stop cleanly and still print the summary.
    $trapKeys = $false
    if (-not [Console]::IsInputRedirected) {
        try { [Console]::TreatControlCAsInput = $true; $trapKeys = $true } catch { $trapKeys = $false }
    }
    if (-not $trapKeys) { Write-Verbose 'No interactive console, so Ctrl+C ends the script without a summary. Use -Duration.' }

    $pinger  = [System.Net.NetworkInformation.Ping]::new()
    $started = Get-Date
    $stopAt  = if ($Duration -gt [timespan]::Zero) { $started + $Duration } else { [datetime]::MaxValue }
    $stop    = $false
    Write-Host ("Watching {0} every {1}s. Logging to {2}. Press Ctrl+C or Q to stop." -f ($targets -join ', '), $IntervalSeconds, $LogPath)

    try {
        while (-not $stop -and (Get-Date) -lt $stopAt) {
            $roundStart = Get-Date
            foreach ($t in $targets) {
                $s = $state[$t]
                $now = Get-Date
                $latency = $null; $status = 'Down'; $detail = $null
                try {
                    $reply = $pinger.Send($t, $TimeoutMs)
                    if ($reply.Status -eq [System.Net.NetworkInformation.IPStatus]::Success) { $status = 'Up'; $latency = $reply.RoundtripTime }
                    else { $detail = [string]$reply.Status }
                }
                catch {
                    # Usually a name that won't resolve. Log it as a miss rather than stopping the whole watch.
                    $detail = $_.Exception.GetBaseException().Message
                }

                $s.Sent++
                $change = $null
                if ($status -eq 'Up') {
                    $s.Received++; $s.TotalMs += $latency
                    if ($latency -gt $s.MaxMs) { $s.MaxMs = $latency }
                    if ($s.IsDown) {
                        $outage = $s.Outages[$s.Outages.Count - 1]
                        $outage.Ended = $now
                        $outage.Duration = $now - $outage.Started
                        $change = 'CameBack'
                        Write-Host ("{0:HH:mm:ss}  {1} is back after {2:hh\:mm\:ss}" -f $now, $t, $outage.Duration) -ForegroundColor Green
                    }
                    $s.IsDown = $false; $s.Misses = 0; $s.FirstMiss = $null
                }
                else {
                    if ($s.Misses -eq 0) { $s.FirstMiss = $now }
                    $s.Misses++
                    if (-not $s.IsDown -and $s.Misses -ge $DownAfter) {
                        $s.IsDown = $true
                        $s.Outages.Add([pscustomobject]@{ ComputerName = $t; Started = $s.FirstMiss; Ended = $null; Duration = $null; Reason = $detail })
                        $change = 'WentDown'
                        Write-Host ("{0:HH:mm:ss}  {1} is DOWN ({2})" -f $now, $t, $(if ($detail) { $detail } else { 'no reply' })) -ForegroundColor Red
                    }
                }

                $row = [pscustomobject]@{
                    Timestamp    = $now.ToString('yyyy-MM-dd HH:mm:ss')
                    ComputerName = $t
                    Status       = $status
                    LatencyMs    = $latency
                    Change       = $change
                    Detail       = $detail
                }
                try { $row | Export-Csv -LiteralPath $LogPath -Append -NoTypeInformation -Encoding utf8 -ErrorAction Stop }
                catch { Write-Warning "Couldn't write to ${LogPath}: $($_.Exception.Message)" }
            }

            # Sleep in small slices so a keypress is noticed quickly.
            $wakeAt = $roundStart.AddSeconds($IntervalSeconds)
            while (-not $stop -and (Get-Date) -lt $wakeAt -and (Get-Date) -lt $stopAt) {
                if ($trapKeys -and [Console]::KeyAvailable) {
                    $key = [Console]::ReadKey($true)
                    if ($key.Key -eq 'Q' -or ($key.Key -eq 'C' -and ($key.Modifiers -band [ConsoleModifiers]::Control))) { $stop = $true }
                }
                Start-Sleep -Milliseconds 200
            }
        }
    }
    finally {
        if ($trapKeys) { [Console]::TreatControlCAsInput = $false }
        $pinger.Dispose()
    }

    $ended = Get-Date
    foreach ($s in $state.Values) {
        # An outage still open at the end runs to the moment we stopped.
        foreach ($o in $s.Outages | Where-Object { -not $_.Ended }) { $o.Duration = $ended - $o.Started }
        $down = [timespan]::Zero
        foreach ($o in $s.Outages) { $down += $o.Duration }
        [pscustomobject]@{
            ComputerName  = $s.Name
            Sent          = $s.Sent
            Received      = $s.Received
            LossPercent   = if ($s.Sent) { [math]::Round(100 * ($s.Sent - $s.Received) / $s.Sent, 1) } else { 0 }
            AvgMs         = if ($s.Received) { [math]::Round($s.TotalMs / $s.Received, 1) } else { $null }
            MaxMs         = if ($s.Received) { $s.MaxMs } else { $null }
            Outages       = $s.Outages.Count
            TotalDowntime = $down
            LongestOutage = ($s.Outages | Sort-Object Duration -Descending | Select-Object -First 1).Duration
            StillDown     = $s.IsDown
            OutageList    = $s.Outages.ToArray()
            LogPath       = $LogPath
        }
    }
}