命令行与文本处理 / 系统课时
生成日志与巡检报告
生成日志与巡检报告
本课把巡检对象转换为可检索的 JSON 日志、可筛选的 CSV 明细、机器可读的 JSON 汇总和人工可读的 Markdown 报告,并用统一状态和阈值字段突出异常主机与关键指标。
学习目标
- 设计日志、明细和汇总三类输出的字段边界
- 使用 PowerShell 一次生成 JSONL、CSV、JSON 与 Markdown 文件
- 验证异常数量、平均指标和报告标识是否一致
先设计输出职责
结构化日志记录“何时发生了什么”,适合按事件追踪执行过程;CSV 明细保留每台主机的一行结果,便于筛选和交付;JSON 汇总提供总数、异常数和聚合指标,适合接口或后续自动化;Markdown 报告只呈现关键结论和异常项,避免把全部原始字段堆给读者。
四类输出应共享稳定字段,例如 HostName、Status、CpuPercent 和 DiskFreePercent。异常判断必须在生成输出前统一完成,不能让 CSV、JSON 与报告各自计算一套规则,否则同一次巡检会出现不同结论。
从巡检对象到多种报告

图中的关键不是文件格式,而是先形成标准化巡检对象,再从同一数据源派生不同视图。这样异常主机数、平均 CPU 和最低磁盘剩余比例只计算一次,所有报告天然保持一致。
主示例:生成四类输出文件
下面脚本使用三条固定样例数据演示完整流水线。WARN 表示主机可达但指标越过阈值,ERROR 表示巡检本身失败;Markdown 报告只列出非 OK 主机,并用警示符号突出状态。
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> 代表当前系统的临时目录,实际值可能不同:
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' 的结果完全一致。
生产环境还应补充执行批次号、脚本版本和主机分组,并对日志目录设置保留周期。若报告需要发送邮件或上传平台,应传递文件路径或对象存储地址,不要把超长明细直接拼进消息正文。