什么是结构化日志(Structured Logging)?为什么它是可观测性的基石
结构化日志为事件记录稳定的字段、类型和上下文。本文讲解如何从文本日志迁移、统一时间与级别、用 Pipeline 归一化,并用字段查询和聚类检查结果。
结构化日志(Structured Logging)是用有明确含义和类型的字段记录日志事件的实践。 JSON 是一种常见编码;可读的消息仍可保留。字段经过提取、映射并可查询时,可以按服务、事件类型和耗时过滤或聚合。
核心要点速览
- 结构化日志是用机器可读的字段记录事件的实践,有助于跨服务查询日志。
- 六步落地:选格式 → 配置日志框架与组件 → Pipeline 解析继续采集的旧格式 → 统一 Schema → 字段归一化。
- 观测云的
time和status分别用于事件时间与日志级别。按级别告警还需配置检测规则。 - 结构化的价值靠分析兑现:查看器字段检索 + 聚类分析 + 仪表板趋势。
传统文本日志为什么走不通了
非结构化日志是写给人看的:
2026-08-25T08:55:00Z [INFO] 用户 user123 从 192.168.0.1 登录
2026-08-25T08:55:01Z [ERROR] 数据库连接失败:Connection refused
"几个服务 + 本地文件 + SSH 排查"的时代这够用。排查跨服务问题时,自由文本仍可搜索;要稳定提取字段,则需要与格式匹配的解析规则,并处理缺失值与格式变更。
以上第二类事件可写成下面的结构化记录。时间、耗时与链路 ID 均为示意:
{
"time": "2026-08-25T08:55:01Z",
"status": "error",
"message": "database connection failed",
"service": "order",
"event": "checkout.failed",
"error_code": "DB_CONNECT_ERROR",
"duration_ms": 1200,
"trace_id": "00000000000000000000000000000001"
}
变化不只是形式。字段经采集和映射后,可以按 error_code 找同类错误、按 service 汇总。用 duration_ms 比较耗时前应确认存储类型是数值。按 IP 或用户分组只能提供排查线索,不能单独确认攻击。
结构化日志的四个特征
- 机器可读格式:采用 JSON 等标准格式,支撑自动化处理;
- 键值对组织:每个键代表明确属性(时间、级别、消息);
- 携带上下文:支持跨服务关联;
- 支持层级嵌套:JSON 可表达对象和数组;接收端能否按嵌套字段过滤或聚合,取决于解析和字段映射。
形象类比:非结构化日志像没有索引的图书馆——书都在,但找不到;结构化日志给每本书贴上索书号,检索效率天差地别。
落地结构化日志的六个步骤(观测云路径)
1. 选定机器可解析格式
先选采集端能稳定解析的编码。JSON 是常见选择,Logfmt 也适合简单键值对。若不同环境输出不同格式,要验证各自的解析规则。
2. 采用结构化日志框架
Java 的 Log4j2/Logback、Node.js 的 Pino、Go 的 slog、Python 的 Structlog 等。例如在 Go 中,原本可能把上下文拼进文本:
log.Printf("请求 %s 处理失败:%v\n", r.ID, err)
变为:
package main
import (
"log/slog"
"os"
)
func main() {
logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
logger.Error("database connection failed",
"service", "order",
"event", "checkout.failed",
"error_code", "DB_CONNECT_ERROR",
"duration_ms", 1200,
)
}
上例需要 Go 1.21 或更新版本,用 slog.NewJSONHandler 显式输出 JSON。处理器默认生成 time、level、msg;接入时可将后两者映射到 status、message,并规范级别值。 Go slog 文档
3. 配置基础设施组件
检查 Nginx、PostgreSQL 等组件能否输出采集器支持的格式。以 PostgreSQL 15+ 为例,log_destination = 'jsonlog' 还要求启用 logging_collector,后者在服务器启动时生效。确认日志路径和轮转策略后再切换采集。 PostgreSQL 日志配置
4. 管道层转换存量文本日志
无法改造的老系统,可以用观测云 Pipeline 对经过管道的文本提取级别、时间和业务字段。先用样本验证成功、字段缺失和解析失败时的输出;已入库的历史记录不会因新增采集规则自动改写。性能开销按实际格式、规则和负载核对。 Pipeline 快速开始
5. 建立统一字段规范(Schema)
这是最易被忽视、也最关键的一步。设想服务 A 把时间写作 Unix 格式的 time,服务 B 写作 ISO 8601 的 timestamp——跨服务排障时查询必须兼顾两种写法,既繁琐又易漏。
统一 Schema 后,可在配置的来源、索引和时间范围内用同一组条件查询:
L("default")::checkout:(count(*) AS error_events)
{ `status` = "error" AND `event` = "checkout.failed" }
[1787648100000:1787648400000] BY service
示例使用 default 索引、source=checkout 和 2026-08-25 08:55–09:00 UTC 的时间窗口。来源由采集配置指定;执行时改成实际来源、索引和时间范围。查询统计日志条数,不能直接当成失败请求数或错误率。不必一步到位,先从核心服务对齐字段和类型,可参考 OpenTelemetry 日志数据模型。
6. 用标准字段完成归一化
在观测云中,可在 Pipeline 提取并设置日志事件时间 time,将来源级别映射到 status。事件发生时间与采集端观察到事件的时间要区分;时间解析失败时按约定保留原值或标记失败。再按业务或环境配置日志索引与存储策略。 日志索引
六条结构化日志最佳实践
- 给每个请求分配唯一 ID 并全链路透传:有活跃链路上下文时,注入真实的
trace_id,必要时记录span_id区分 Span。观测云整条链路的日志默认按trace_id匹配,日志索引还受服务字段映射和权限影响;链路与日志都要已采集且仍保留。 关联日志配置 · 链路详情; - 充分富化上下文:只添加能回答问题的字段,采集前排除凭据和不必要的个人信息;
- 尽早推行统一 Schema:避免后期返工;
- 字段名带单位:
response_time_ms而非response_time; - 保留可读的 message 字段:结构化不等于放弃人读;
- 异常堆栈结构化:可以分别记录错误类型、消息与堆栈;逐帧结构是否必要,按查询需求和体积决定。
结构化之后,用起来才算数
结构化的价值要在分析平台兑现。观测云中两个典型动作:在日志查看器按已解析、可查询的字段筛选。聚类分析可按 message 等字段在当前条件下归并相似记录;要核对总量,使用明确索引、时间范围和过滤条件的计数。也可以在仪表板按字段聚合并单独配置监控器告警。只结构化却不分析,就像整理好图书馆却从不开放借阅。
总结
非结构化日志也能用于排障;稳定的字段类型和映射使跨服务过滤、聚合与关联更可靠。落地路径:选格式、换框架、统一 Schema、Pipeline 归一——然后让数据为你工作。
常见问题(FAQ)
Q:结构化日志就是 JSON 日志吗?
JSON 是常见编码;Logfmt 也可以表达简单键值对。单纯把一整行文本包进 JSON,只增加了外层格式。关键上下文仍需要有含义明确的字段。
Q:老系统改造工作量大吗?
工作量取决于日志框架、已有采集规则和下游查询。可以先为仍在采集的文本配置解析,再逐步迁移产生日志的应用。核对格式、字段类型、解析失败和告警兼容性。
Q:结构化日志会影响性能吗?
开销来自序列化、字段数量、写入量以及采集与索引处理。用实际负载检查应用延迟、吞吐和日志体积。