Semantic Logger 实战指南：Ruby 生态的结构化日志框架

Semantic Logger 是 Ruby 生态中的结构化日志框架：默认异步写入、多 appender、结构化 payload、性能埋点一应俱全，且与 Rails 深度集成。本文从安装配置讲到生产实践，帮助你充分发挥它的能力，并落地到观测云平台。

核心要点速览

• 默认异步，队列满时可能阻塞：日志进队列由独立线程处理；正常退出时尝试 flush，异常终止不能保证排空。同步模式应在添加 appender 前配置。
• 多 appender 是核心设计：控制台 + 文件 + HTTP 端点同时输出，每个 appender 独立级别与格式。
• payload 参数实现结构化：logger.info("msg", {user_id: 1})，字段进 JSON 的 payload 键。
• measure 系列方法：一条日志同时完成"记录 + 耗时度量"，慢操作筛查利器。

安装与快速上手

# Gemfile
gem "semantic_logger"

require "semantic_logger"

SemanticLogger.add_appender(io: $stdout)
logger = SemanticLogger["OrderService"]

logger.info("服务启动")
logger.error("发生错误")

输出自带时间戳、级别、进程/线程 ID 与 logger 名：

2026-08-25 14:45:22.173156 I [1294858:60] OrderService -- 服务启动

类里注入 logger 用 Loggable mixin：

class OrderService
  include SemanticLogger::Loggable

  def process(order)
    logger.info("处理订单", { order_id: order.id })
  end
end

日志自动归属于类名，模块级排障时定位飞快。

异步模式：性能与可靠性的取舍

Semantic Logger 默认异步：logger.info 通常把消息放进队列，由独立线程负责写入。队列满时调用仍可能阻塞；5.x 默认队列容量为 10,000 条，可按版本和负载调整。日志格式化、入队及背压仍有开销，进程崩溃时队列中未写的日志可能丢失。

• 正常退出时尝试 flush，也可手动 SemanticLogger.flush；强制终止和崩溃不保证完成；
• 需要"写完才返回"的场景（命令行工具、审计）切同步：Gemfile 里 gem "semantic_logger", require: "semantic_logger/sync"，或在启动时、添加 appender 前调用 SemanticLogger.sync!；不要把它当作运行中任意切换的开关；同步返回也不等于磁盘已fsync或远端已持久确认。

结构化字段：payload 与异常

每个级别方法的签名：logger.info(message, payload_or_exception = nil, exception = nil, &block)。

# payload 结构化字段
logger.info("用户登录", { user_id: user.id, ip: request.remote_ip })

# 异常：自动记录类型、消息与完整堆栈
begin
  raise "支付网关超时"
rescue => e
  logger.error("扣款失败", { order_id: 1024 }, e)
end

JSON formatter 下输出：

{"host":"web-01","timestamp":"2026-08-25T14:46:03.873Z","level":"error","name":"OrderService","message":"扣款失败","payload":{"order_id":1024},"exception":{"name":"RuntimeError","message":"支付网关超时","stack_trace":["..."]}}

异常堆栈自动结构化——这是比标准库 Logger 手动拼 backtrace 省心得多的地方。

采集前先选一条带 payload 的业务日志和一条异常日志检查 JSON 输出。经观测云 DataKit读取后，验证 timestamp、level 与需要查询的 payload 子字段，按约定映射事件时间和级别；measure 产生的 duration_ms 要保留为数值，才便于比较慢操作。

多 appender 配置

# 控制台：彩色，接收通过 logger 级别过滤的日志
SemanticLogger.add_appender(io: $stdout, formatter: :color)

# 文件：JSON，只收 error 及以上
require "fileutils"
FileUtils.mkdir_p("logs")
SemanticLogger.add_appender(file_name: "logs/error.log", formatter: :json, level: :error)

每个 appender 可独立设置级别、格式与过滤器，但先被全局或 logger 级别过滤掉的日志不会到达 appender；控制台也只能看到通过前置过滤的记录。appender 生态覆盖文件、TCP/UDP、HTTP、MongoDB 等，但推荐的应用架构仍是只写 stdout/文件，转发交给采集层（观测云 DataKit），让应用与日志后端解耦。

measure 方法：日志与性能埋点二合一

logger.measure_info("调用支付网关", metric: "PaymentGateway/request_time", min_duration: 1000) do
  gateway.charge(order)
end

块执行完毕自动产生一条带 duration_ms 字段的日志；min_duration: 1000 表示只有耗时超 1 秒才记录——慢操作筛查不再靠人肉翻日志。metric 是日志中的度量标识，不会自动创建平台指标。只记录超过阈值的请求时，聚合结果是慢请求样本的平均耗时，不能代表全部请求。示例中的 gateway 和 order 由业务代码提供。

动态调整级别

排障时不想重启？开启信号处理：

SemanticLogger.add_signal_handler

之后 kill -SIGUSR2 <pid> 会让全局级别在 fatal → error → warn → info → debug → trace 间轮切，生产排障开到 debug，定位后再切回去，全程不重启；信号要发送给实际 Ruby 进程，且不会自动覆盖 logger 或 appender 已显式设置的级别。

Rails 集成

Gemfile 加入后，可用 rails_semantic_logger 获得完整 Rails 集成：替换 Rails.logger、自动标记请求、可配置 JSON 输出。需要关联链路时，还应配置追踪上下文注入，并用一次请求核对日志中的 trace_id。

常见问题（FAQ）

Semantic Logger 和标准库 Logger 能共存吗？

能。它兼容标准 Logger API，也可以作为 Rails.logger 的底层。渐进迁移时可以混用；已有的标准库 Logger 实例不会自动接入 Semantic Logger 的 appender，需要显式替换或桥接。

异步模式日志顺序会乱吗？

默认异步处理使用共享处理队列，并非每个 appender 都有独立队列。队列顺序不能代表多个线程或进程之间的业务因果顺序，网络目的地也可能有额外缓冲；同步模式同样不能建立跨进程全局顺序。

measure 的耗时日志量太大怎么办？

用 min_duration 阈值只记慢操作，或对高频路径采样。进观测云后还可以用低频索引进一步压成本。

生产环境推荐哪些 appender？

一个就够：stdout + JSON formatter（容器）或文件 + JSON（主机配 logrotate）。让采集层负责后续转发；如使用网络 appender，应另外验证阻塞、重试和失败时的行为。

系列阅读

• 上一篇：Ruby 日志库六款对比
• 下一篇：.NET 日志入门
• 相关阅读：Rails 日志实战 ｜ 日志最佳实践总论

---