Ruby on Rails 使用 Lograge：把默认日志整理成更适合生产环境的结构化输出

时间：2026-08-23 | 作者：冻月看渠 | 阅读：0

前言

Rails 默认日志在开发阶段很方便，但到了生产环境，信息过多往往意味着文件膨胀、检索困难，接入日志平台时也不够顺手。Lograge 适合用来把一次请求整理成更紧凑的结构化记录，本文会结合安装配置、示例日志和常见排查点，帮助你判断它是否值得接入当前项目。

Rails 默认日志信息量很大，调试阶段很有用，但一到生产环境，日志体积、检索效率和接入分析平台的成本就会很快冒出来。Lograge 的价值不在于“少打日志”这么简单，而是把一次请求收敛成更适合检索、聚合和监控的一条结构化记录；下面从安装配置、关键选项、输出字段和常见问题几部分展开，方便你判断这套方案是否适合自己的 Rails 应用。

为什么 Rails 项目会考虑用 Lograge

在 Ruby on Rails 应用中，日志记录本来就是运行时观测的重要入口。但 Rails 默认会为一次请求输出较多细节，包括 SQL 查询、模板渲染和控制器处理过程。信息足够全面，代价就是日志文件容易迅速膨胀，后续筛查和集中分析也会更麻烦。

lograge 的核心思路，是把分散的请求日志压缩为更简洁的单行输出。如果再配合 JSON 格式，就更适合接入 Kibana、ELK Stack 一类日志分析工具。

Lograge 的安装与基础配置

先把依赖加进项目

先在 Gemfile 中加入 lograge：

Lograge 配置项与输出路径关系图 — **Lograge 基础配置关系图**把启用开关、输出格式、日志目标和自定义字段放在一张图里，更容易看懂 Lograge。

gem 'lograge'

然后运行 bundle install 完成安装。

在初始化文件里启用并定义输出格式

常见做法是在 config/initializers/lograge.rb 中集中配置。下面这段示例保留了原始配置内容，可直接作为理解入口：

// www.ja vascriptcn.com code example
# config/initializers/lograge.rb

Lograge.enabled = true

# 禁用默认的日志格式
Lograge::Logger.class_eval do
  def format_message(name, start, finish, real_duration, message)
    message.to_s
  end
end

# 设置日志输出格式
Lograge.formatter = Lograge::Formatters::Json.new

# 将日志输出到控制台或文件
Rails.application.configure do
  config.lograge.enabled = true
  config.lograge.base_controller_class = 'ActionController::API'
  config.lograge.logger = ActiveSupport::Logger.new(STDOUT)
  config.lograge.custom_options = lambda do |event|
    {
      timestamp: event.time.strftime('%Y-%m-%dT%H:%M:%S.%6NZ'),
      params: event.payload[:params].except('controller', 'action')
    }
  end
end

这几个配置项分别在做什么

Lograge.enabled：控制是否启用 Lograge。
Lograge.formatter：这里指定为 Lograge::Formatters::Json.new，也就是让日志按 JSON 结构输出。
config.lograge.logger：定义日志写到哪里。示例里使用 STDOUT，这在容器化部署或集中采集场景里比较常见。
config.lograge.custom_options：补充默认日志之外的字段。示例额外加入了 timestamp，同时通过 except('controller', 'action') 排除了参数里的部分重复字段。
config.lograge.base_controller_class：示例设置为 'ActionController::API'，更贴近 API 型 Rails 应用的控制器基类。

用了 Lograge，能解决哪些实际问题

1. 日志体积更容易控制

默认 Rails 日志会把一次请求拆成多段信息输出，细节很多，但也更占空间。Lograge 的做法是只保留一次请求里最关键的数据，因此日志量通常会明显下降。

这对请求量较高的应用尤其有意义：日志写入成本下降后，文件增长速度、归档压力和检索开销都会跟着缓和一些。

2. 记录开销更低，生产环境更省事

日志本身也要消耗 I/O 和处理资源。虽然 Lograge 并不是性能优化工具，但在减少冗余日志输出之后，通常可以间接减轻日志记录对应用运行的影响。

在生产环境里，这种变化往往比开发环境更有感知，因为生产流量更大，日志采集链路也更完整。

3. 更适合机器处理和日志平台接入

如果日志最终要进入 Kibana 或 ELK Stack，一条结构完整的 JSON 记录，远比多行文本更容易解析、索引和过滤。对于故障排查、接口性能分析和访问趋势观察，这类结构化日志会更顺手。

启用后的日志长什么样

按照上面的配置启用后，一条请求日志大致会是下面这个样子：

Lograge JSON 日志字段组成与用途图 — **一条 Lograge 日志包含哪些关键信息**把一条 JSON 请求日志拆成请求信息、处理结果、耗时数据和附加上下文四组。

// www.ja vascriptcn.com code example
{
  "timestamp": "2023-04-15T12:34:56.789123Z",
  "method": "GET",
  "path": "/api/v1/users",
  "format": "*/*",
  "controller": "Api::V1::UsersController",
  "action": "index",
  "status": 200,
  "duration": 123.456,
  "view": 78.912,
  "db": 45.678,
  "params": {
    "limit": "10"
  },
  "remote_ip": "192.168.1.1"
}