可观测性与稳定性 / 系统课时
接入后台应用 JSON 日志
接入后台应用 JSON 日志
这一练习把后台应用已经输出的 JSON 日志接入集中平台,并在采集阶段补齐 environment、host、service 三个统一字段。完成后,你可以用同一组字段跨主机、跨服务筛选日志,而不再依赖各应用自定义的文件名或目录。
学习目标
- 让 Fluent Bit 按 JSON 解析应用日志,而不是把整行当作普通文本。
- 在采集侧统一补齐环境、主机和服务字段。
- 通过集中平台查询确认字段已经正确写入。
先固定应用日志结构
应用侧应尽量直接输出结构化 JSON。下面是一条可写入 /var/log/order-api/app.json 的日志记录,时间统一使用 UTC,业务关联字段使用稳定名称。
{"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 和集中存储四个对象,同时还要区分“解析字段”和“部署字段”,用数据流图更容易看清字段是在什么位置加入的。

下面给出一套最小配置。parsers.conf 负责把每一行 JSON 解析成字段,并把 timestamp 识别为日志时间。
[PARSER]
Name app_json
Format json
Time_Key timestamp
Time_Format %Y-%m-%dT%H:%M:%S.%LZ
Time_Keep Onfluent-bit.conf 读取日志文件,使用环境变量补齐部署字段,再写入 OpenSearch。实验环境可以使用明文 HTTP;生产环境应按平台要求配置 TLS 和认证。
[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>。
printf '%s\n' '{"timestamp":"2026-09-18T03:00:00.000Z","level":"INFO","message":"order created","request_id":"req-demo-1403","duration_ms":42}' >> <PATH>预期输出
(无标准输出)然后从集中平台按 request_id 查询,并只返回 _source,这样可以直接检查统一字段是否存在。
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"
}
}
}'预期结果
{"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 命名。