命令行与文本处理 / 系统课时

生成日志与巡检报告

生成日志与巡检报告

本课把巡检对象转换为可检索的 JSON 日志、可筛选的 CSV 明细、机器可读的 JSON 汇总和人工可读的 Markdown 报告,并用统一状态和阈值字段突出异常主机与关键指标。

学习目标

  • 设计日志、明细和汇总三类输出的字段边界
  • 使用 PowerShell 一次生成 JSONL、CSV、JSON 与 Markdown 文件
  • 验证异常数量、平均指标和报告标识是否一致

先设计输出职责

结构化日志记录“何时发生了什么”,适合按事件追踪执行过程;CSV 明细保留每台主机的一行结果,便于筛选和交付;JSON 汇总提供总数、异常数和聚合指标,适合接口或后续自动化;Markdown 报告只呈现关键结论和异常项,避免把全部原始字段堆给读者。

四类输出应共享稳定字段,例如 HostName、Status、CpuPercent 和 DiskFreePercent。异常判断必须在生成输出前统一完成,不能让 CSV、JSON 与报告各自计算一套规则,否则同一次巡检会出现不同结论。

从巡检对象到多种报告

巡检日志与报告数据流

图中的关键不是文件格式,而是先形成标准化巡检对象,再从同一数据源派生不同视图。这样异常主机数、平均 CPU 和最低磁盘剩余比例只计算一次,所有报告天然保持一致。

主示例:生成四类输出文件

下面脚本使用三条固定样例数据演示完整流水线。WARN 表示主机可达但指标越过阈值,ERROR 表示巡检本身失败;Markdown 报告只列出非 OK 主机,并用警示符号突出状态。

powershell
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

$outputDirectory = Join-Path $env:TEMP 'host-inspection-report'
New-Item $outputDirectory -ItemType Directory -Force | Out-Null

$logPath = Join-Path $outputDirectory 'inspection.jsonl'
$csvPath = Join-Path $outputDirectory 'host-details.csv'
$summaryPath = Join-Path $outputDirectory 'summary.json'
$reportPath = Join-Path $outputDirectory 'report.md'
Remove-Item $logPath, $csvPath, $summaryPath, $reportPath `
    -Force -ErrorAction SilentlyContinue

function Write-StructuredLog {
    param(
        [ValidateSet('INFO', 'WARN', 'ERROR')]
        [string]$Level,
        [string]$Event,
        [hashtable]$Data
    )

    [ordered]@{
        timestamp = (Get-Date).ToString('o')
        level     = $Level
        event     = $Event
        data      = $Data
    } |
        ConvertTo-Json -Depth 6 -Compress |
        Add-Content $logPath -Encoding utf8
}

$records = @(
    [pscustomobject]@{
        HostName = 'web-01'; Reachable = $true; CpuPercent = 42
        FreeMemoryMB = 4096; DiskFreePercent = 36
        Status = 'OK'; ErrorMessage = ''
    }
    [pscustomobject]@{
        HostName = 'web-02'; Reachable = $true; CpuPercent = 91
        FreeMemoryMB = 1536; DiskFreePercent = 8
        Status = 'WARN'; ErrorMessage = ''
    }
    [pscustomobject]@{
        HostName = 'db-01'; Reachable = $false; CpuPercent = $null
        FreeMemoryMB = $null; DiskFreePercent = $null
        Status = 'ERROR'; ErrorMessage = 'WinRM connection failed'
    }
)

foreach ($record in $records) {
    $level = if (-not $record.Reachable) {
        'ERROR'
    }
    elseif ($record.Status -eq 'WARN') {
        'WARN'
    }
    else {
        'INFO'
    }

    Write-StructuredLog -Level $level -Event 'HostInspected' -Data @{
        host   = $record.HostName
        status = $record.Status
        cpu    = $record.CpuPercent
        disk   = $record.DiskFreePercent
        error  = $record.ErrorMessage
    }
}

$records | Export-Csv $csvPath -NoTypeInformation -Encoding utf8

$reachable = @($records | Where-Object { $_.Reachable })
$abnormal = @($records | Where-Object { $_.Status -ne 'OK' })
$summary = [ordered]@{
    generatedAt            = (Get-Date).ToString('o')
    totalHosts             = $records.Count
    reachableHosts         = $reachable.Count
    abnormalHosts          = $abnormal.Count
    averageCpuPercent      = [math]::Round(
        ($reachable | Measure-Object CpuPercent -Average).Average, 1
    )
    minimumDiskFreePercent = (
        $reachable | Measure-Object DiskFreePercent -Minimum
    ).Minimum
}

$summary | ConvertTo-Json |
    Set-Content $summaryPath -Encoding utf8

$lines = [System.Collections.Generic.List[string]]::new()
$lines.Add('# 主机巡检报告')
$lines.Add('')
$lines.Add("总主机数:$($summary.totalHosts)")
$lines.Add("异常主机数:$($summary.abnormalHosts)")
$lines.Add("平均 CPU:$($summary.averageCpuPercent)%")
$lines.Add("最低磁盘剩余:$($summary.minimumDiskFreePercent)%")
$lines.Add('')
$lines.Add('## 异常主机')
$lines.Add('')
$lines.Add('| 主机 | 状态 | CPU | 磁盘剩余 | 异常说明 |')
$lines.Add('|---|---:|---:|---:|---|')

foreach ($record in $abnormal) {
    $cpu = if ($null -eq $record.CpuPercent) {
        '-'
    }
    else {
        "$($record.CpuPercent)%"
    }
    $disk = if ($null -eq $record.DiskFreePercent) {
        '-'
    }
    else {
        "$($record.DiskFreePercent)%"
    }
    $message = if ($record.ErrorMessage) {
        $record.ErrorMessage
    }
    else {
        '关键指标超阈值'
    }

    $lines.Add(
        "| $($record.HostName) | ⚠ $($record.Status) | $cpu | $disk | $message |"
    )
}

$lines | Set-Content $reportPath -Encoding utf8

Write-Host 'Generated files:'
Write-Host "  log     : $logPath"
Write-Host "  details : $csvPath"
Write-Host "  summary : $summaryPath"
Write-Host "  report  : $reportPath"
Write-Host (
    "Summary: total=$($summary.totalHosts) " +
    "reachable=$($summary.reachableHosts) " +
    "abnormal=$($summary.abnormalHosts) " +
    "avgCpu=$($summary.averageCpuPercent)% " +
    "minDisk=$($summary.minimumDiskFreePercent)%"
)

预期输出如下,<PATH> 代表当前系统的临时目录,实际值可能不同:

text
Generated files:
  log     : <PATH>/host-inspection-report/inspection.jsonl
  details : <PATH>/host-inspection-report/host-details.csv
  summary : <PATH>/host-inspection-report/summary.json
  report  : <PATH>/host-inspection-report/report.md
Summary: total=3 reachable=2 abnormal=2 avgCpu=66.5% minDisk=8%

生成的 Markdown 报告会列出 web-02 和 db-01,分别标记为 ⚠ WARN 与 ⚠ ERROR。JSONL 中每行都是独立 JSON 对象,即使脚本中途停止,已经写入的日志仍可逐行读取。

验收与落地要点

验收时先对照源对象数量,确认 CSV 行数、日志事件数和汇总总数一致;再核对异常主机数、平均 CPU 与最低磁盘剩余比例。报告中的异常列表必须与 Status -ne 'OK' 的结果完全一致。

生产环境还应补充执行批次号、脚本版本和主机分组,并对日志目录设置保留周期。若报告需要发送邮件或上传平台,应传递文件路径或对象存储地址,不要把超长明细直接拼进消息正文。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

生成日志与巡检报告

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通