可观测性与稳定性 / 系统课时

接入后台应用 JSON 日志

接入后台应用 JSON 日志

这一练习把后台应用已经输出的 JSON 日志接入集中平台,并在采集阶段补齐 environment、host、service 三个统一字段。完成后,你可以用同一组字段跨主机、跨服务筛选日志,而不再依赖各应用自定义的文件名或目录。

学习目标

  • 让 Fluent Bit 按 JSON 解析应用日志,而不是把整行当作普通文本。
  • 在采集侧统一补齐环境、主机和服务字段。
  • 通过集中平台查询确认字段已经正确写入。

先固定应用日志结构

应用侧应尽量直接输出结构化 JSON。下面是一条可写入 /var/log/order-api/app.json 的日志记录,时间统一使用 UTC,业务关联字段使用稳定名称。

json
{"timestamp":"2026-09-18T03:00:00.000Z","level":"INFO","message":"order created","request_id":"req-demo-1403","duration_ms":42}

这里不要把环境、主机名硬编码进应用日志。它们通常属于部署上下文,由日志 Agent 在采集时统一补齐,更容易在不同环境复用同一应用镜像。

用 Fluent Bit 解析并补齐字段

数据链路包含应用、日志文件、Fluent Bit 和集中存储四个对象,同时还要区分“解析字段”和“部署字段”,用数据流图更容易看清字段是在什么位置加入的。

后台应用 JSON 日志从文件到集中平台的数据流

下面给出一套最小配置。parsers.conf 负责把每一行 JSON 解析成字段,并把 timestamp 识别为日志时间。

ini
[PARSER]
    Name        app_json
    Format      json
    Time_Key    timestamp
    Time_Format %Y-%m-%dT%H:%M:%S.%LZ
    Time_Keep   On

fluent-bit.conf 读取日志文件,使用环境变量补齐部署字段,再写入 OpenSearch。实验环境可以使用明文 HTTP;生产环境应按平台要求配置 TLS 和认证。

ini
[SERVICE]
    Parsers_File parsers.conf

[INPUT]
    Name              tail
    Tag               app.order
    Path              /var/log/order-api/app.json
    Parser            app_json
    DB                /var/lib/fluent-bit/order-api.db
    Read_from_Head    On
    Refresh_Interval  1

[FILTER]
    Name   record_modifier
    Match  app.*
    Record environment ${LOG_ENV}
    Record service     ${LOG_SERVICE}
    Record host        ${HOSTNAME}

[OUTPUT]
    Name               opensearch
    Match              app.*
    Host               <HOST>
    Port               <PORT>
    Index              logs-app
    Suppress_Type_Name On
    Retry_Limit        False

启动 Fluent Bit 前,为进程设置 LOG_ENV 和 LOG_SERVICE。HOSTNAME 通常由主机或容器运行环境提供;如果运行环境没有该变量,应显式传入。

写入一条日志并验证

启动 Agent 后,向被采集文件追加一条唯一测试日志。实际日志路径可能不同,应替换 <PATH>。

bash
printf '%s\n' '{"timestamp":"2026-09-18T03:00:00.000Z","level":"INFO","message":"order created","request_id":"req-demo-1403","duration_ms":42}' >> <PATH>

预期输出

text
(无标准输出)

然后从集中平台按 request_id 查询,并只返回 _source,这样可以直接检查统一字段是否存在。

bash
curl -s -X POST "http://<HOST>:<PORT>/logs-app/_search?filter_path=hits.hits._source" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match_phrase": {
        "request_id": "req-demo-1403"
      }
    }
  }'

预期结果

json
{"hits":{"hits":[{"_source":{"timestamp":"2026-09-18T03:00:00.000Z","level":"INFO","message":"order created","request_id":"req-demo-1403","duration_ms":42,"environment":"<ENV>","service":"<SERVICE>","host":"<HOSTNAME>"}}]}}

environment、service 和 host 的实际值取决于 Fluent Bit 进程收到的环境变量,因此生产环境看到的值会与示例不同。

接入失败时先看哪里

如果查询不到日志,先检查 Fluent Bit 是否能读取文件,再检查输出端,而不是直接修改索引。DB 文件记录 Tail 读取偏移,文件权限不足、路径错误或旧偏移都可能让“应用有日志但平台没有数据”。

如果日志能写入但字段没有拆开,重点检查 Parser app_json 是否生效以及输入是否真的是一行一个 JSON 对象。若 message 中包含 Java 异常栈等多行内容,应先在应用侧转义换行,或在采集侧配置 multiline 规则,避免一个事件被拆成多条。

最终验收标准不是“平台里有一行文本”,而是能稳定检索到结构化字段,并且不同服务都使用相同的 environment、host、service 命名。

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

目录与阅读设置

阅读设置

17

记录一个想法

接入后台应用 JSON 日志

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

登录哪都通