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

设计结构化日志

设计结构化日志

脚本一旦进入计划任务、远程执行或批量运维场景,普通字符串日志就很难检索,也容易混入业务输出。本课将建立固定日志契约,把级别、时间、任务编号、主机与异常统一写入 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 聚合;业务函数赋值后不会得到额外日志字符串。若后续接入集中式日志平台,保持字段契约不变,只替换写入目标即可。

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

目录与阅读设置

阅读设置

17

记录一个想法

设计结构化日志

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

登录哪都通