ActiveRecord Query Trace 技术文档

1. 安装指南

1.1 环境要求

• Ruby 版本 >= 2.7
• Rails 版本 6.0、6.1 或 7.0

1.2 安装步骤

1. 在 Gemfile 中添加以下内容：

   group :development do
     gem 'active_record_query_trace'
   end
   

2. 创建一个初始化文件，例如 config/initializers/active_record_query_trace.rb，并在其中启用该 gem。如果需要自定义 gem 的行为，可以在初始化文件中添加以下配置选项：

   if Rails.env.development?
     ActiveRecordQueryTrace.enabled = true
     # 可选：其他 gem 配置选项可以在这里添加
   end
   

3. 重启 Rails 开发服务器。

2. 项目的使用说明

2.1 启用查询追踪

在开发环境中，启用 active_record_query_trace 后，每次执行数据库查询时，日志中都会显示查询的调用栈信息。这有助于追踪查询在应用程序中的执行位置，特别是在性能优化或大型应用程序中进行更改时。

2.2 日志示例

启用后，日志将显示如下内容：

D, [2019-03-03T19:50:41.061115 #25560] DEBUG -- : User Load (0.1ms)  SELECT "users".* FROM "users"
D, [2019-03-03T19:50:41.062492 #25560] DEBUG -- : Query Trace:
      app/models/concerns/is_active.rb:11:in `active?'
      app/models/user.rb:67:in `active?'
      app/decorators/concerns/status_methods.rb:42:in `colored_status'
      app/views/shared/companies/_user.html.slim:28:in `block in _app_views_users_html_slim___2427456029761612502_70304705622200'
      app/views/shared/companies/_user.html.slim:27:in `_app_views_users_html_slim___2427456029761612502_70304705622200'

3. 项目 API 使用文档

3.1 配置选项

3.1.1 调用栈级别

有三种调试级别可供选择：

• :app - 仅包含应用程序的调用栈（位于 Rails.root 目录下的文件）；
• :rails - 包含除应用程序之外的所有调用栈（所有不在 Rails.root 目录下的文件）；
• :full - 完整的调用栈（包含所有文件），适用于调试 gem。

ActiveRecordQueryTrace.level = :app # 默认值

如果需要更多控制，可以使用 :custom 级别并提供自定义的调用栈清理器：

ActiveRecordQueryTrace.level = :custom
require "rails/backtrace_cleaner"
ActiveRecordQueryTrace.backtrace_cleaner = Rails::BacktraceCleaner.new.tap do |bc|
  bc.remove_filters!
  bc.remove_silencers!
  bc.add_silencer { |line| line =~ /\b(active_record_query_trace|active_support|active_record|another_gem)\b/ }
end

3.1.2 查询类型

可以选择仅为读取或写入操作显示调用栈：

• :all - 显示所有查询的调用栈；
• :read - 仅显示数据库读取操作（SELECT）的调用栈；
• :write - 仅显示数据库写入操作（INSERT, UPDATE, DELETE）的调用栈。

ActiveRecordQueryTrace.query_type = :all # 默认值

3.1.3 抑制数据库读取查询日志

如果设置为 true，此选项将抑制所有由数据库读取操作（SELECT）生成的日志行，仅保留由数据库写入操作生成的日志行。注意，整个日志行都会被抑制，而不仅仅是调用栈。

ActiveRecordQueryTrace.suppress_logging_of_db_reads = false # 默认值

3.1.4 忽略缓存查询

默认情况下，每次查询都会记录调用栈，即使是不实际访问数据库的缓存查询。你可以选择不为缓存查询打印调用栈：

ActiveRecordQueryTrace.ignore_cached_queries = true # 默认值为 false

3.1.5 限制调用栈行数

如果应用程序较大，你可能希望限制每次查询显示的调用栈行数。如果将 level 设置为 :full，你可能希望将 lines 设置为 0，以便查看完整的调用栈。

ActiveRecordQueryTrace.lines = 10 # 默认值为 5。设置为 0 将包含完整的调用栈。

3.1.6 调用栈颜色

可以为调用栈输出着色：

ActiveRecordQueryTrace.colorize = false           # 无颜色（默认）
ActiveRecordQueryTrace.colorize = :light_purple   # 使用特定颜色着色

有效颜色包括：:black, :red, :green, :brown, :blue, :purple, :cyan, :gray, :dark_gray, :light_red, :light_green, :yellow, :light_blue, :light_purple, :light_cyan, :white。

4. 项目安装方式

4.1 通过 Gemfile 安装

在 Gemfile 中添加以下内容：

group :development do
  gem 'active_record_query_trace'
end

4.2 创建初始化文件

在 config/initializers/ 目录下创建一个初始化文件，例如 active_record_query_trace.rb，并在其中启用 gem：

if Rails.env.development?
  ActiveRecordQueryTrace.enabled = true
  # 可选：其他 gem 配置选项可以在这里添加
end

4.3 重启服务器

完成上述步骤后，重启 Rails 开发服务器以使配置生效。

结语

通过 active_record_query_trace，你可以轻松追踪应用程序中的数据库查询，帮助你在性能优化和代码修改时快速定位问题。希望本文档能帮助你更好地理解和使用该工具。