Linux 与服务器运维 / 系统课时
给运维脚本加入结构化日志
给运维脚本加入结构化日志
运维脚本只打印“开始”“成功”“失败”,出现故障时很难检索和关联。本节把日志统一成 JSON Lines:每行都是独立 JSON,固定记录时间、级别、动作、目标、耗时和执行标识,让部署、巡检和故障处置日志能够被机器解析和集中检索。
学习目标
- 设计稳定的结构化日志字段,减少对自由文本搜索的依赖
- 用统一日志函数记录动作、目标、耗时和执行结果
- 使用
run_id关联同一次脚本执行产生的多条日志
定义稳定的日志字段
结构化日志的重点不是“看起来像 JSON”,而是字段名称和含义长期稳定。一个实用的最小集合可以包含 timestamp、level、run_id、action、target、duration_seconds 和 message。
其中 action 应采用固定词汇,例如 backup、deploy、restart、health_check;target 保存服务、主机或文件等具体对象;message 只补充人类可读信息。以后查询某个服务所有失败的健康检查时,就不需要猜脚本当时打印了什么中文文案。
实现统一日志函数
下面示例使用 jq 负责 JSON 转义,避免目标名称或错误文本中的双引号破坏日志格式。脚本会模拟一次健康检查,并输出开始和完成两条日志。
#!/usr/bin/env bash
set -euo pipefail
if ! command -v jq >/dev/null 2>&1; then
printf 'jq is required\n' >&2
exit 127
fi
RUN_ID="${RUN_ID:-$(date +%s)-$$}"
now_iso8601() {
date -u '+%Y-%m-%dT%H:%M:%SZ'
}
log_json() {
local level="$1"
local action="$2"
local target="$3"
local duration_seconds="$4"
local message="$5"
jq -cn --arg timestamp "$(now_iso8601)" --arg level "$level" --arg run_id "$RUN_ID" --arg action "$action" --arg target "$target" --argjson duration_seconds "$duration_seconds" --arg message "$message" '{timestamp:$timestamp,level:$level,run_id:$run_id,action:$action,target:$target,duration_seconds:$duration_seconds,message:$message}'
}
health_check() {
local target="$1"
local started_at="$SECONDS"
local duration
log_json "INFO" "health_check" "$target" 0 "started"
# 用短暂等待模拟真实的 HTTP、进程或数据库健康检查。
sleep 1
duration=$((SECONDS - started_at))
log_json "INFO" "health_check" "$target" "$duration" "completed"
}
health_check "api-service"运行脚本:
./ops-log.sh预期输出:
{"timestamp":"<TIME>","level":"INFO","run_id":"<ID>","action":"health_check","target":"api-service","duration_seconds":0,"message":"started"}
{"timestamp":"<TIME>","level":"INFO","run_id":"<ID>","action":"health_check","target":"api-service","duration_seconds":1,"message":"completed"}<TIME> 和 <ID> 是动态值,实际运行时分别对应 UTC 时间和本次执行标识。第二条日志的耗时通常为 1 秒,但系统调度导致的实际值可能略有不同。每一行都能独立解析,因此适合按行采集。
让失败日志保留原因
失败记录不能只写 failed,否则集中日志系统只能告诉你“失败了”,却无法说明失败对象和原因。真实步骤应保留动作、目标以及命令返回的错误信息,同时把非零退出状态继续返回给调用方。
下面是可以接入前面日志函数的片段示例,依赖已经定义的 log_json 和 Bash 内置变量 SECONDS:
started_at="$SECONDS"
if curl --fail --silent --show-error --max-time 3 "http://127.0.0.1:8080/health" >/dev/null; then
duration=$((SECONDS - started_at))
log_json "INFO" "health_check" "api-service" "$duration" "completed"
else
status=$?
duration=$((SECONDS - started_at))
log_json "ERROR" "health_check" "api-service" "$duration" "curl failed with exit_code=$status"
exit "$status"
fi这段代码不是独立脚本,需要放入主示例已经定义日志函数的上下文中。验证时可以让 127.0.0.1:8080 保持无服务状态,日志应产生 level 为 ERROR 的记录,同时脚本以真实的 curl 非零退出码结束。
用 run_id 串起一次执行
一次部署往往包含备份、上传、重启和健康检查多步操作。若每条日志只有时间,很难在并发执行时判断哪些记录属于同一次任务。run_id 就是用于解决这个问题的关联键。
流水线已有任务 ID 时,优先从外部传入:
RUN_ID="deploy-<ID>" ./ops-log.sh预期输出:
{"timestamp":"<TIME>","level":"INFO","run_id":"deploy-<ID>","action":"health_check","target":"api-service","duration_seconds":0,"message":"started"}
{"timestamp":"<TIME>","level":"INFO","run_id":"deploy-<ID>","action":"health_check","target":"api-service","duration_seconds":1,"message":"completed"}这样 CI/CD 平台、Shell 日志和后续告警都能使用同一个执行标识。没有外部 ID 时,示例脚本才会根据时间戳和进程号生成本地标识。
验证日志可以被机器检索
结构化日志落地前,应至少做一次解析验证,而不是仅凭肉眼判断格式。先把输出保存,再查询所有健康检查动作:
./ops-log.sh > ops.log
jq -r 'select(.action == "health_check") | [.level, .target, .message] | @tsv' ops.log预期输出:
INFO api-service started
INFO api-service completed这证明每一行都是可解析记录,而不是拼接出来的“类 JSON”文本。后续接入 Filebeat、Fluent Bit、Vector 或其他采集系统时,只需按行读取并映射这些稳定字段,就可以围绕 level、action、target 和 run_id 建立检索与告警规则。