CONCEPT Cited by 1 source

Rails query log tags¶

Definition¶

Rails query log tags are Rails 7+'s native ActiveRecord feature for automatically appending a trailing SQL comment to every ActiveRecord-issued query, carrying structured per-request metadata (controller, action, job, application name, custom tags). The feature was absorbed into the framework in Rails 7, superseding the Marginalia gem for the default case.

Enable envelope¶

Three config.active_record.* settings control the feature:

# config/application.rb
config.active_record.query_log_tags_enabled = true
config.active_record.query_log_tags = [
  :application, :controller, :action, :job
]
config.active_record.cache_query_log_tags = true

query_log_tags_enabled — master switch.
query_log_tags — array of tag symbols to emit on every query. Built-in tag vocabulary: :application, :controller, :action, :job, :namespace_name, :pid, :hostname, :database, :source_location, plus pluggable custom tags (proc or symbol).
cache_query_log_tags — memoise the rendered tag string per request so every query in the same request doesn't re-render the tags. Production deployments should set this to true.

(Source: sources/2026-04-21-planetscale-identifying-slow-rails-queries-with-sqlcommenter; canonical framework reference: Rails Query Logs API.)

Default emission format¶

Rails's default format is a Rails-convention key:value comma-separated list:

SELECT * FROM users ORDER BY id DESC LIMIT 1
/*application:Api,controller:users,action:show*/

This is not SQLCommenter format. SQLCommenter uses key='value' pairs with single-quoted values:

SELECT * FROM users ORDER BY id DESC LIMIT 1
/*application='Api',controller='users',action='show'*/

Third-party tools that parse SQLCommenter natively (PlanetScale Insights, Google Cloud SQL Insights, most observability vendors) can't read the Rails-default format. The activerecord-sql_commenter gem swaps the emission format while keeping the same query_log_tags configuration surface.

Per-request vs per-query scope¶

The built-in tags are per-request — populated by controller, action, and job middleware once per request and emitted on every query that issues during that request. For per-query overrides ("this specific query comes from the user-metrics job, regardless of what controller owns the request"), use ActiveRecord's annotate(...) method:

User.where(name: "iheanyi").annotate("source='user_metrics_runner'")

The two mechanisms compose — query_log_tags provides the per-request baseline tags, annotate adds per-query overrides or extensions on top.

Relationship to the Marginalia gem¶

Rails 7's query_log_tags is the framework-absorbed successor to the Marginalia gem (Basecamp). Same idea, same class of emitted tags, similar default format — but no gem required for Rails 7+ apps using the default case. Apps on Rails 6 and earlier continue to rely on Marginalia.

Seen in¶

sources/2026-04-21-planetscale-identifying-slow-rails-queries-with-sqlcommenter — canonical wiki introduction. Coutermarsh + Ekechukwu (2022-06-29) establish the pre-history (Marginalia) → present (Rails 7 query_log_tags) → SQLCommenter-format migration (via activerecord-sql_commenter) story. The three-settings enable envelope is disclosed verbatim, the default emission format is shown byte-for-byte, and the annotate per-query override is introduced as the complementary escape hatch.