Logfmt 入门：一种兼顾人机体验的结构化日志格式

Logfmt 是一种用 key=value 键值对表示日志的结构化格式，每对键值之间以空格分隔。 它最早由 Heroku 推广，因既方便人类直接阅读、又能被机器轻松解析，成为 JSON 之外的热门结构化日志选择。

一条典型的 Logfmt 日志：

level=info host=web-01 service=order msg="数据库连接成功"

其中 level 是键、info 是值——不需要任何工具就能读懂，解析器也能稳定提取每个字段。

核心要点速览

• Logfmt 是以空格分隔 key=value 键值对的结构化日志格式，兼顾人类可读与机器可解析。
• 它是扁平格式：点号"伪嵌套"不被解析器识别，层级数据请直接用 JSON。
• 推荐双格式策略：开发环境用 Logfmt（人读友好），生产环境用 JSON（平台友好）。
• 接入观测云：DataKit 采集后由 Pipeline 切割字段，并提取标准字段 time 与 status。

Logfmt 如何处理嵌套数据

Logfmt 本质是扁平格式，社区约定用点号（.）模拟层级：

level=info msg="应用运行正常" app.status=ok app.uptime_hours=720

概念上等价于 JSON 的嵌套对象，但请注意：绝大多数 Logfmt 解析器并不识别这种"伪嵌套"——解析后得到的仍是扁平键值对，键名就是 app.status 这个字面字符串。

因此，如果日志重度依赖层级数据表达，应直接使用 JSON 而非 Logfmt。

Logfmt 使用最佳实践

• 键名不含空格：统一使用蛇形命名（snake_case），避免解析歧义；
• 键名只用字母数字：保持解析规则简单可靠；
• 接受扁平本质：不要硬塞层级结构；
• 每条日志以换行结尾：主流框架自动处理；
• 开发环境上色：彩色键值显著提升扫读效率。

Logfmt 与 JSON 对比

务实策略：两个都要——开发环境输出 Logfmt（肉眼扫读友好），生产环境输出 JSON（平台处理友好）。以 Go 的 slog 为例，按环境变量切换 Handler 即可：

var handler slog.Handler
if os.Getenv("APP_ENV") == "production" {
    handler = slog.NewJSONHandler(os.Stdout, nil)  // 生产：JSON
} else {
    handler = slog.NewTextHandler(os.Stdout, nil)  // 开发：Logfmt 风格
}
logger := slog.New(handler)
logger.Warn("磁盘空间不足", "available", "900 MB")

开发环境输出：

time=2026-08-25T10:00:04+08:00 level=WARN msg="磁盘空间不足" available="900 MB"

生产环境输出：

{"time":"2026-08-25T10:00:04+08:00","level":"WARN","msg":"磁盘空间不足","available":"900 MB"}

在观测云中处理 Logfmt 日志

如果系统已在使用 Logfmt，接入观测云无需改造应用：DataKit 采集原始文本后，用 Pipeline 脚本按 key=value 规律切割提取字段即可。两个关键动作：

1. 提取标准字段：把日志级别映射为 status、日志时间映射为 time——这两个字段决定查看器的状态着色、时间线与按级别检索 ；
2. 字段命名归一：Logfmt 键名进入平台后即成为可检索字段，建议遵循全公司统一的命名规范（如 service、user_id），便于跨服务关联。

生产环境若可从源头输出 JSON，则更省心：JSON 日志通常可直接解析，Pipeline 只需做少量字段映射。

各语言 Logfmt 生态

主流语言均有成熟编解码库：Node.js（logfmt）、Go（slog 的 TextHandler 内建支持）、Python（logfmter）、Java、Ruby、Rust、PHP 等，覆盖绝大多数技术栈。

总结

Logfmt 以最小的语法噪音实现了结构化日志的核心目标：机器可解析、人类易阅读。它不适合复杂嵌套，但在扁平键值对的主场——尤其是开发环境——体验优于 JSON。"开发 Logfmt、生产 JSON"的双格式策略配合观测云 Pipeline，是兼顾两端体验的成熟做法。

常见问题（FAQ）

Q：Logfmt 中的值什么时候需要加引号？
值包含空格或特殊字符时用双引号包裹（如 msg="连接数据库失败"）；简单值可裸写（如 level=info）。

Q：观测云查看器能直接识别 Logfmt 吗？
需要先用 Pipeline 切割成字段，之后即可按字段筛选、聚合与告警。切割规则是一次性配置，长期受益。

Q：Logfmt 和 JSON 二选一选哪个？
只选一种时选 JSON：平台生态与嵌套支持更好。Logfmt 更适合作为开发环境的人读格式。

---

系列阅读：JSON 日志入门 ｜ 什么是结构化日志