日志:结构化事件的叙事力量

上一篇结尾留了一道墙:指标把一万个请求坍缩成一个 +N,那些请求作为个体的许多细节,在聚合时就消失了。于是它能告诉你“错误率 8%”,却通常答不出“是哪些请求、哪些用户、走的哪条路”。

日志,给这道墙开了一扇窗。它为每一个被选中、值得记下的事件留下一条记录,把时间、结果和当时能取得的上下文带到排障现场。这是本书的天平第一次明确往“留住个体”的方向挪动。但留下多少、留多久、能问到多深,仍然是取舍。日志从早期系统一路走进云原生,工具换了几轮,问题没有变:怎样用机器保存的细节,节省人重新拼现场的注意力?

一、留下个体:日志在做什么

指标坍缩个体,日志留下个体

把指标和日志放在同一个场景下看,区别一目了然。一个用户登录失败了:

  • 指标的反应:login_failures_total 这条序列的值 +1。如果没有相应标签,这个用户是谁、从哪登的、为什么失败——都不会随这次 +1 留下。
  • 日志的反应:写下一条记录——“2026-06-06 14:32:07,用户 8f3a 从 192.0.2.10 登录失败,原因:密码错误,这是他第三次尝试。”这里使用的是示例身份和文档地址。

指标擅长存聚合测量,日志擅长存事件记录。指标问“发生了多少次”,日志问“那一次留下了什么证据”。个体不再只剩一个数字——但记录仍然是现场的选择性切片,不是现场本身。

日志的定义:一个事件的记录

收紧成定义:一条日志,是对系统中某个事件的记录。 它通常带着三样东西——什么时候(时间戳)、什么事(事件描述)、相关上下文(谁、哪里、什么结果)。字段可能缺失,时钟可能偏移,输出也可能在缓冲或传输时丢失;“完整”应当是我们对关键事件约定的质量目标,不能作为日志天然拥有的属性。

这里要引入一个影响深远的视角,来自 12-factor app:把应用日志当作事件流,而不是由业务代码管理的一组文件。 应用把事件交给标准输出,运行环境负责收集、路由和保留。这是容器场景很有用的职责划分;既有文件日志、系统日志也可以接入同一条管道。事件跨机器之后不会天然保持全局时间顺序,需要保留事件时间、采集时间和关联字段。

力量与边界同源

和前两篇一样,日志的力量和边界,也是同一件事的两面:

日志能留下“这里发生了什么”;它与别处怎样相关,取决于你有没有把关联信息一并留下。

力量在于保留事件上下文——出了问题,你能翻到那一条,找到聚合曲线背后的细节。边界在于日志不会自动组织成完整因果图。即使在单体应用里,并发请求的记录也会交错;当请求跨越十个服务,靠时间戳手工拼接就更脆弱。这是本篇第五节的主题。

二、从文本到数据:结构化这一跳

日志能不能成为有用的信号,很大程度取决于它是否同时照顾了人的阅读和机器的查询。这就是结构化与非结构化的分野,也是日志这一篇最关键的工程决策。

非结构化日志的代价

传统的日志长这样:

2026-06-06 14:32:07 ERROR User 8f3a failed login from 192.0.2.10 after 3 attempts

它为人眼优化——一句通顺的英文,扫一眼就懂。但当你想做聚合分析时,额外工作就来了。“过去一小时,哪个 IP 的登录失败最多?”——你得先写正则、切分文本,把 192.0.2.10 抠出来,再分组计数。grep 配合其他工具当然能完成这件事,代价是每种格式都要维护解析约定,格式一变可能悄悄漏数。非结构化日志把数据腌进了散文里,机器和人都得费点劲再把它抠出来。

结构化日志:字段即提问的入口

结构化日志把同一个事件写成机器能直接读的格式——通常是 JSON:

{
  "timestamp": "2026-06-06T14:32:07Z",
  "level": "warn",
  "event": "login_failed",
  "user_id": "8f3a",
  "source_ip": "192.0.2.10",
  "reason": "wrong_password",
  "attempt": 3
}

现在“哪个 IP 失败最多”有了稳定的字段入口:按 source_ip 分组、计数。日志从“可以搜索的文本”,变成了更容易查询的数据。这一跳,帮助我们回答 指标答不出的那个“哪一个”——前提是写日志时记下了相关字段,采集时没有丢失,查询端也正确解释了它。

JSON 只是容器,字段语义才是契约。duration 是毫秒还是秒?user_id 在两个服务里指向同一个身份吗?一次失败重试三次,是三条尝试事件还是一个最终失败事件?这些约定不清楚,机器只是更快地算出一个含义不明的数字。

日志级别的语义:注意力阀门的一层输入

日志有级别——DEBUG / INFO / WARN / ERROR / FATAL——但很多人把它用乱了。级别是 注意力阀门的一层输入:它先回答“记录者认为这件事有多严重”,再由处理规则决定是否打扰人。 不同日志库的具体级别不尽相同,团队需要自己的语义约定。

  • DEBUG:排查实现细节的线索,按需开启或受控采样;不等于可以随意写敏感数据。
  • INFO:正常流程中的关键事件,供事后回溯;不必给每一步都拍一张照片。
  • WARN:偏离预期但尚能继续,例如重试、降级;需要结合频率和结果判断影响。
  • ERROR:某项操作失败,留下足够的上下文以便调查。
  • FATAL:通常表示进程无法继续;是否退出、怎样退出取决于日志库与调用方式。

一条 ERROR 不等于一次 page,一条 INFO 也可能记录关键用户操作失败。登录密码输错可能是预期业务结果;连续大批失败才需要调查。叫醒人应由用户影响、持续时间、可行动性和责任归属决定,不能只靠日志字面级别。 级别划分仍然重要:定低了,筛选失效;定高了,线索难找。它是对未来排障者注意力的预先分配。

字段设计的纪律:该记什么、绝不该记什么

结构化的自由是有代价的——你得管好字段。

  • 不应进入普通日志的内容:密码、token、密钥、完整支付凭据。原始请求体和个人身份信息也不能因为“以后可能有用”就整段复制;先确定目的、最少字段、脱敏和访问范围。
  • 高基数可以有,但要放对地方:request_id、trace_id 适合帮助定位个体,具体用户标识则按必要性和隐私要求决定。它们会增加数据量或查询成本,也可能在错误的索引设计下制造基数问题。
  • 稳定的公共骨架:事件名、事件时间、服务与版本、环境、结果、耗时单位、关联标识;可选字段缺失时要有统一含义。
  • 管道也有质量要求:重复、丢失、乱序、解析失败、时钟偏差应能被发现;关键审计事件的完整性要求,通常高于调试日志。

字段设计本质上是在问:未来排障的人,会需要哪些维度来切分和定位? 这仍然是预判——预判的是要保留哪些证据,为未来的问题留多少余地。

三、经典实践:ELK 的索引世界

理论落地。ELK——Elasticsearch + Logstash + Kibana,以及周边的 Beats——是日志工程里一条影响深远的技术路线。看懂它,就能理解“提前建立更丰富的检索结构”怎样换取事后查询能力。

12-factor:应用交出事件,环境管理去向

在容器应用里,业务代码可以把结构化事件写到 stdout,运行环境把它送入 ELK。遗留应用写文件也没关系,由采集器接上。这样,应用与目的后端的耦合会减少;但字段、格式和保留约定仍然需要共同维护,换后端也可能涉及映射和查询迁移。

采集管道:从机器到中心

日志从应用流到能查询的地方,要穿过一条管道:

应用 stdout / 文件 → Filebeat / Fluentd → Logstash → Elasticsearch → Kibana
                     采集与缓冲          解析与富化    存储与索引       查询与展示

这是一种常见组合,不要求每一跳都存在:

  • Filebeat / Fluentd:读取日志并转发;要检查读取权限、缓冲、断点与重试策略。
  • Logstash:管道的“加工车间”——解析文本、补环境元数据、转换字段。已经有稳定 JSON 时,工作可以很轻;遗留文本往往需要更多解析规则。
  • Elasticsearch:根据字段映射存储和建立查询结构。
  • Kibana:查询、聚合和可视化。

“采集器在线”只证明进程在,不能证明日志已经完整入库。挑一条带唯一测试标识的事件,从产生、采集到查询走一遍,才知道这条管道是否接通。

Elasticsearch 的倒排索引:查询能力要付账

Elasticsearch 可以为 text 字段分析、分词并建立全文检索索引,为 keyword 等字段提供精确匹配与聚合;也可以关闭某些字段的索引。不是每条日志的每个词都必须建索引,也不是任意查询都能毫秒返回。 字段映射、查询方式和数据规模会共同决定行为。Elastic:text、keyword、index 参数

代价来自索引、原文、列式值、副本以及查询资源的组合;压缩和保留策略又会改变账单。不能脱离配置断言“索引总比原文大”,但更丰富的检索能力确实会带来需要评估的资源与运维成本。你为更快、更灵活地找到证据付了一笔税;税值不值,要拿自己的日志和问题来算。

Kibana:从搜索到聚合

结构化字段让日志可以参与统计:按 source_ip 分组数失败次数、按 reason 看分布、观察 login_failed 事件随时间的变化。日志开始干一部分指标的活,但两者没有因此等价。如果日志被采样、重复发送或丢失,算出来的是“收到的日志记录数”,未必是完整业务次数。要把它作为 SLI,先验证覆盖率和事件计数口径。

四、云原生实践:Loki 的“少建索引”哲学

Grafana Loki 选择了一种不同的交换方式:让低基数标签承担主要索引,把日志正文压缩保存,再在查询时过滤。这是 指标那篇“存储汇率”标尺的又一次现身。

Loki 的反向取舍:索引先定位日志流

Loki 的基础设计是用标签索引定位日志流,而不为日志正文建立 Elasticsearch 那样的全文倒排索引。一条记录可以带有低基数标签、时间戳、正文,以及可选的 structured metadata(结构化元数据)。

例如标签是 {app="checkout", env="prod"},正文是一行 JSON。先找服务和环境,再读相应时间范围内的块。这样可以减少索引负担,但扫描量大时仍然需要查询算力;对象存储、缓存、分片和查询加速也都需要维护。少付索引税,可能意味着查询时多做一些工作。 “低成本”是待实测的优势,不是无条件的账单保证。

采集:label 怎么打,基数幽灵重现

新建采集链路可以使用 Grafana Alloy。Promtail 已于 2026-03-02 结束维护;旧教程中的配置可以帮助理解历史,但不再作为本书的新建默认方案。Grafana:Promtail 生命周期

下面是本地文件读取的最小概念示例。它假设 Alloy 能读取该文件,Loki 可达;生产环境还需配置认证、持久化读取位置、轮转处理和资源限制。Kubernetes 日志则需要额外的发现、权限与采集规则。Alloy:文件采集

loki.source.file "checkout" {
  targets = [{
    __path__ = "/var/log/checkout/app.log",
    app      = "checkout",
    env      = "prod",
  }]
  forward_to = [loki.write.local.receiver]
}
 
loki.write "local" {
  endpoint {
    url = "http://loki:3100/loki/api/v1/push"
  }
}

注意 基数的幽灵又回来了:标签组合会产生日志流,不应把每次请求一个值的 request_id、trace_id 放进索引标签。它们可以保存在 JSON 正文,或在满足 Loki schema、存储和接收配置条件时作为 structured metadata 附着在记录上。后者不建立普通标签索引,查询时也无需重新解析正文,但仍占用存储和传输额度。Loki:structured metadata

“什么进索引标签、什么放正文、什么作为结构化元数据”,是用 Loki 的核心纪律。高基数从来没有消失;我们只是给它选择了不同的付费位置。

LogQL:先缩范围,再过滤

Loki 的查询语言 LogQL,结构上体现了这个取舍:

{app="checkout", env="prod"}
  |= "login_failed"
  | json
  | level = "warn"
  | source_ip = "192.0.2.10"

先通过标签和时间范围缩小候选日志流,再进行文本、JSON 字段过滤。这里的 level 留在正文;如果已经约定它是低基数索引标签,也可以移进大括号选择器。大括号里的标签选择,与管道后提取字段的过滤,是两种不同动作。 缩完范围还有多少数据、能否接受查询延迟,仍然要用实际负载验证。

ES vs Loki:两种索引取舍

把两者并排,你会发现它们是 存储汇率标尺上的两种常见选择,配置不同也会改变各自的位置:

Elasticsearch(ELK)Loki
主要检索结构按字段映射建立全文、精确匹配等结构以低基数标签索引定位流,正文按查询过滤
查询优势多种字段查询和聚合,适合丰富检索需求已知服务、环境和时间范围下的日志探索
成本来源索引、原文、副本、保留与查询资源日志块、索引、扫描、缓存与保留
运维工作映射、分片、副本、容量与生命周期标签、采集、对象存储、容量与查询负载
选择依据用代表性的查询测延迟、成本和维护工作量用同一组数据与问题比较,不只看组件数量

选哪个,又回到那个永恒的问题:你愿意为“未来找得到答案”付多少机器资源和人的维护时间? 熟悉现有平台、查询频率、数据量、保留要求都会改变汇率。没有标准答案,但可以有一张能够复核的账单。

五、边界:关联字段不等于完整因果链

日志保留了个体,能参与聚合,索引策略还能丰俭由人。它看起来很全能。但如果关联信息没有留下,开篇埋的那颗雷,在并发系统里就会引爆。

★ 故障剧场:拼不出的旅程

一个用户报告:“我的结账失败了。”你去查日志。

这个请求经过了五个服务:网关 → 订单 → 库存 → 支付 → 通知。每个服务都老老实实记了日志。于是你在五个服务的日志流里,分别看到了一些 error:

  • 网关在 14:32:07 记了一条 request received;
  • 支付服务在 14:32:09 记了一条 payment declined;
  • 库存服务在 14:32:08 记了一条 lock timeout……

哪几条属于这一个用户的这一次请求? 同一秒里,系统处理了上千个请求。你想把“这一次结账”的旅程拼出来,却没有稳定字段证明这些记录属于同一条链。时间接近只是线索,不能自动构成因果关系。

孤立性不是宿命,关联需要设计

一条日志可以是一个点,也可以带上连接到其他点的标识。在单体里,同一线程有时能提供线索,但异步、协程和线程复用都会削弱这种办法。跨进程之后,更要明确约定关联标识如何生成、传播和记录。时钟同步能帮助排列现场,却不能替代这条关联线。

trace_id:找到同一次追踪中的记录

同一次追踪中的日志可以记录同一个 trace_id,再用 span_id 标记所处操作。标识由追踪上下文生成或从上游接续,应用、框架或自动插桩需要正确传播;仅仅给日志加个字段,不会让下游自动拥有它。OpenTelemetry:日志数据模型

{ "timestamp": "...", "service": "gateway", "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "event": "request_received" }
{ "timestamp": "...", "service": "payment", "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "event": "payment_declined", "reason": "insufficient_funds" }

在 Loki 中,如果标识位于 JSON 正文,查询写成:

{env="prod"} | json | trace_id = "4bf92f3577b34da6a3ce929d0e0e4736"

如果它作为 structured metadata 存入,则不需要 | json。不要写成 {trace_id="..."}:那会要求它成为前面刚刚反对的索引标签。

找到相同 trace_id 的记录,只说明它们属于同一追踪上下文。要重建调用方向、父子关系、持续时间和并行关系,还需要 span 结构、传播约定和相应记录。 日志有缺口、采样不同步或重试关系复杂时,仍可能拼不完整。关联字段把搜索范围缩小了,追踪再把这些关系组织起来。

跨越工具代际的信号

日志从早期系统保留到今天,因为它有不可替代的价值:它允许开发者记录业务结果、错误语境和运行时细节。它也可以由代理和运行时自动产生。两者都会受到字段、采样和保留策略约束。

因此,“留下个体、支持事后提问”并不是某个时代的专属能力。日志一直在这条路上,只是结构化、关联约定和查询工具让这条路更好走了。下一篇要讨论的 可观测性,会把这种能力提升为有意识的系统设计目标。

六、小结:坐标与去向

日志在五维标尺上的坐标

用 那把尺子定位日志,关注取舍,不给工具排年代:

维度日志作出的选择
① 预先判断与事后探索预先选择事件与字段,为未来未预设的查询保留余地
② 信息保留的粒度留下个体,以采样、保留、索引和扫描策略调节成本
③ 信号的分工补充“发生了什么”和事件上下文,与其他信号相互核对
④ 注意力的阀门级别帮助筛选;真正通知人还要结合影响和处置需要
⑤ 仪器化的负担业务日志需要语义设计,自动采集承担搬运与公共元数据

天平向“留住信息”挪了一格,但不是留下越多越好。一万条重复报错可能只会淹没一个关键上下文;一条精心设计的结果事件,可能省下半小时的猜测。机器保存了多少,不如人在需要时能否找到足够的证据。

实践收束:先让一条关键事件走通

选择一个重要操作,为它写清事件名、成功与失败含义、时间和耗时单位、关联字段与隐私处理。先用一个测试事件走通采集和查询,再检查重试、重复、丢失与解析失败。保留期和采样按使用目的决定;承担审计或 SLI 的记录,要单独验证其完整性。到了这一步,再谈扩充日志量,才能知道自己在买什么。

去向:把事件接成可解释的旅程

  • 当需要重建请求在各个操作中的父子关系与耗时,走向 分布式追踪。
  • 当把“为未知问题保留证据”变成系统设计目标,进入 可观测性的讨论。
  • 指标、日志、追踪怎样共享上下文和数据约定,交给 OpenTelemetry。

那个贯穿本书的问题继续向前:这一份多留下来的证据,节省了多少人的注意力,又消耗了多少机器资源? 日志让个体留在桌上,下一步,是把这些个体放回它们发生的关系里。

技术资料核对:2026-10-12。上述配置与查询用于说明接口和取舍,未在本实验台执行验证。

返回 可观测性与运维工程 MOC | 上一篇 03-指标-时间序列的量化哲学 | 下一篇 05-可观测性-从已知失败到任意提问