命令行与文本处理 / 系统课时
设计结构化日志
设计结构化日志
脚本一旦进入计划任务、远程执行或批量运维场景,普通字符串日志就很难检索,也容易混入业务输出。本课将建立固定日志契约,把级别、时间、任务编号、主机与异常统一写入 JSONL 文件,同时让成功输出流只返回业务结果对象。
学习目标
- 设计可稳定检索的结构化日志字段与级别规则
- 使用 PowerShell 输出 JSONL 日志并记录异常上下文
- 将日志流与业务结果对象分离,避免污染管道
先定义日志契约
结构化日志不是“把一句话转成 JSON”,而是先确定每条记录必须满足的字段契约。字段名应长期稳定,字段值负责描述一次事件,这样日志平台才能按任务、主机、级别和时间聚合查询。
| 字段 | 作用 | 建议 |
|---|---|---|
Timestamp |
事件发生时间 | 使用 UTC 和 ISO 8601 格式 |
Level |
严重程度 | 固定为 Debug、Info、Warning、Error |
TaskId |
串联一次任务的全部记录 | 在任务入口生成,向下传递 |
Host |
标识执行节点 | 使用机器名,不依赖用户输入 |
Message |
描述发生了什么 | 写事实,不拼接大段对象文本 |
Exception |
保存异常上下文 | 无异常时为 null,出错时记录类型、消息和堆栈 |
Info 用于关键里程碑,Warning 表示任务仍可继续但存在风险,Error 表示当前动作失败。Debug 只保留诊断细节,并应允许在生产环境关闭。

实现统一日志函数
下面的示例把每条日志序列化为单行 JSON。日志函数不向成功输出流写对象,因此调用任务函数时,变量只接收到业务结果。
powershell
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'
function Write-StructuredLog {
[CmdletBinding()]
param(
[Parameter(Mandatory)]
[ValidateSet('Debug', 'Info', 'Warning', 'Error')]
[string]$Level,
[Parameter(Mandatory)]
[string]$Message,
[Parameter(Mandatory)]
[string]$TaskId,
[Parameter(Mandatory)]
[string]$LogPath,
[System.Exception]$Exception
)
# 固定字段顺序,便于人工阅读,也保证每条记录遵循同一契约。
$record = [ordered]@{
Timestamp = [DateTime]::UtcNow.ToString('o')
Level = $Level
TaskId = $TaskId
Host = [Environment]::MachineName
Message = $Message
Exception = if ($null -eq $Exception) {
$null
}
else {
[ordered]@{
Type = $Exception.GetType().FullName
Message = $Exception.Message
StackTrace = $Exception.StackTrace
}
}
}
$jsonLine = $record | ConvertTo-Json -Depth 5 -Compress
Add-Content -LiteralPath $LogPath -Value $jsonLine -Encoding utf8
}
function Invoke-InventoryTask {
[CmdletBinding()]
param(
[Parameter(Mandatory)]
[string]$Path,
[Parameter(Mandatory)]
[string]$TaskId,
[Parameter(Mandatory)]
[string]$LogPath
)
Write-StructuredLog -Level Info -Message '开始统计文件' `
-TaskId $TaskId -LogPath $LogPath
try {
$fileCount = @(Get-ChildItem -LiteralPath $Path -File).Count
Write-StructuredLog -Level Info -Message '文件统计完成' `
-TaskId $TaskId -LogPath $LogPath
# 成功输出流只返回业务对象,不返回日志对象。
[pscustomobject]@{
TaskId = $TaskId
Path = $Path
FileCount = $fileCount
Success = $true
}
}
catch {
Write-StructuredLog -Level Error -Message '文件统计失败' `
-TaskId $TaskId -LogPath $LogPath -Exception $_.Exception
[pscustomobject]@{
TaskId = $TaskId
Path = $Path
FileCount = 0
Success = $false
}
}
}
$taskId = [Guid]::NewGuid().ToString()
$logPath = Join-Path ([IO.Path]::GetTempPath()) 'inventory-task.jsonl'
Remove-Item -LiteralPath $logPath -ErrorAction SilentlyContinue
$result = Invoke-InventoryTask `
-Path ([IO.Path]::GetTempPath()) `
-TaskId $taskId `
-LogPath $logPath
$result | Format-List TaskId, Success, FileCount
Get-Content -LiteralPath $logPath预期输出
text
TaskId : <ID>
Success : True
FileCount: <N>
{"Timestamp":"<TIME>","Level":"Info","TaskId":"<ID>","Host":"<HOST>","Message":"开始统计文件","Exception":null}
{"Timestamp":"<TIME>","Level":"Info","TaskId":"<ID>","Host":"<HOST>","Message":"文件统计完成","Exception":null}<ID>、<TIME>、<HOST> 和 <N> 会随运行环境变化。关键验证点是:$result 只有一个业务对象,而日志记录单独进入 JSONL 文件。
处理异常与敏感信息
异常字段应保存异常类型、消息和堆栈,但不要直接序列化整个 ErrorRecord,否则容易产生过深对象、冗余字段或序列化失败。日志中也不应写入密码、令牌、连接字符串和完整个人数据。
任务编号必须在入口生成并贯穿后续函数、远程调用和重试。如果一次重试代表同一业务任务,可以保留原 TaskId,再增加 Attempt 字段;如果是完全独立的任务,则生成新的编号。
验收结构化日志
完成实现后,至少检查三件事:每行能被 ConvertFrom-Json 独立解析;同一任务的记录可按 TaskId 聚合;业务函数赋值后不会得到额外日志字符串。若后续接入集中式日志平台,保持字段契约不变,只替换写入目标即可。
按自己的节奏,确认真正理解。