Merge pull request rails#46265 from bdewater/query-logs-docs [ci-skip]

Update Active Record Query Logs docs

Author: p8

activerecord/lib/active_record/query_logs.rb

@@ -6,56 +6,59 @@
 module ActiveRecord
   # = Active Record Query Logs
   #
-  # Automatically tag SQL queries with runtime information.
+  # Automatically append comments to SQL queries with runtime information tags. This can be used to trace troublesome
+  # SQL statements back to the application code that generated these statements.
   #
-  # Default tags available for use:
+  # Query logs can be enabled via Rails configuration in <tt>config/application.rb</tt> or an initializer:
+  #
+  #     config.active_record.query_log_tags_enabled = true
+  #
+  # By default the name of the application, the name and action of the controller, or the name of the job are logged.
+  # The default format is {SQLCommenter}[https://open-telemetry.github.io/opentelemetry-sqlcommenter/].
+  # The tags shown in a query comment can be configured via Rails configuration:
+  #
+  #     config.active_record.query_log_tags = [ :application, :controller, :action, :job ]
+  #
+  # Active Record defines default tags available for use:
   #
   # * +application+
   # * +pid+
   # * +socket+
   # * +db_host+
   # * +database+
   #
-  # _Action Controller and Active Job tags are also defined when used in Rails:_
+  # Action Controller adds default tags when loaded:
   #
   # * +controller+
   # * +action+
-  # * +job+
-  #
-  # The tags used in a query can be configured directly:
+  # * +namespaced_controller+
   #
-  #     ActiveRecord::QueryLogs.tags = [ :application, :controller, :action, :job ]
+  # Active Job adds default tags when loaded:
   #
-  # or via Rails configuration:
-  #
-  #     config.active_record.query_log_tags = [ :application, :controller, :action, :job ]
+  # * +job+
   #
-  # To add new comment tags, add a hash to the tags array containing the keys and values you
-  # want to add to the comment. Dynamic content can be created by setting a proc or lambda value in a hash,
-  # and can reference any value stored in the +context+ object.
+  # New comment tags can be defined by adding them in a +Hash+ to the tags +Array+. Tags can have dynamic content by
+  # setting a +Proc+ or lambda value in the +Hash+, and can reference any value stored by Rails in the +context+ object.
+  # ActiveSupport::CurrentAttributes can be used to store application values. Tags with +nil+ values are
+  # omitted from the query comment.
   #
   # Example:
   #
-  #    tags = [
-  #      :application,
-  #      {
-  #        custom_tag: ->(context) { context[:controller]&.controller_name },
-  #        custom_value: -> { Custom.value },
-  #      }
-  #    ]
-  #    ActiveRecord::QueryLogs.tags = tags
-  #
-  # The QueryLogs +context+ can be manipulated via the +ActiveSupport::ExecutionContext.set+ method.
-  #
-  # Temporary updates limited to the execution of a block:
-  #
-  #    ActiveSupport::ExecutionContext.set(foo: Bar.new) do
-  #      posts = Post.all
-  #    end
-  #
-  # Direct updates to a context value:
-  #
-  #    ActiveSupport::ExecutionContext[:foo] = Bar.new
+  #     config.active_record.query_log_tags = [
+  #       :namespaced_controller,
+  #       :action,
+  #       :job,
+  #       {
+  #         request_id: ->(context) { context[:controller]&.request&.request_id },
+  #         job_id: ->(context) { context[:job]&.job_id },
+  #         tenant_id: -> { Current.tenant&.id },
+  #         static: "value",
+  #       },
+  #     ]
+  #
+  # By default the name of the application, the name and action of the controller, or the name of the job are logged
+  # using the {SQLCommenter}[https://open-telemetry.github.io/opentelemetry-sqlcommenter/] format. This can be changed
+  # via {config.active_record.query_log_tags_format}[https://guides.rubyonrails.org/configuring.html#config-active-record-query-log-tags-format]
   #
   # Tag comments can be prepended to the query:
   #
@@ -64,10 +67,6 @@ module ActiveRecord
   # For applications where the content will not change during the lifetime of
   # the request or job execution, the tags can be cached for reuse in every query:
   #
-  #    ActiveRecord::QueryLogs.cache_query_log_tags = true
-  #
-  # This option can be set during application configuration or in a Rails initializer:
-  #
   #    config.active_record.cache_query_log_tags = true
   module QueryLogs
     mattr_accessor :taggings, instance_accessor: false, default: {}

guides/source/debugging_rails_applications.md

@@ -236,7 +236,34 @@ Below each database statement you can see arrows pointing to the specific source
 
 Verbose query logs are enabled by default in the development environment logs after Rails 5.2.
 
-WARNING: We recommend against using this setting in production environments. It relies on Ruby's `Kernel#caller` method which tends to allocate a lot of memory in order to generate stacktraces of method calls.
+WARNING: We recommend against using this setting in production environments. It relies on Ruby's `Kernel#caller` method which tends to allocate a lot of memory in order to generate stacktraces of method calls. Use query log tags (see below) instead.
+
+SQL Query Comments
+------------------
+
+SQL statements can be commented with tags containing runtime information, such as the name of the controller or job, to
+trace troublesome queries back to the area of the application that generated these statements. This is useful when you are
+logging slow queries (e.g. [MySQL](https://dev.mysql.com/doc/refman/en/slow-query-log.html), [PostgreSQL](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-LOG-MIN-DURATION-STATEMENT)),
+viewing currently running queries, or for end-to-end tracing tools.
+
+To enable, add in `application.rb` or any environment initializer:
+
+```rb
+config.active_record.query_log_tags_enabled = true
+```
+
+By default the name of the application, the name and action of the controller, or the name of the job are logged. The
+default format is [SQLCommenter](https://open-telemetry.github.io/opentelemetry-sqlcommenter/). For example:
+
+```
+Article Load (0.2ms)  SELECT "articles".* FROM "articles" /*application='Blog',controller='articles',action='index'*/
+
+Article Update (0.3ms)  UPDATE "articles" SET "title" = ?, "updated_at" = ? WHERE "posts"."id" = ? /*application='Blog',job='ImproveTitleJob'*/  [["title", "Improved Rails debugging guide"], ["updated_at", "2022-10-16 20:25:40.091371"], ["id", 1]]
+```
+
+The behaviour of [`ActiveRecord::QueryLogs`](https://api.rubyonrails.org/classes/ActiveRecord/QueryLogs.html) can be
+modified to include anything that helps connect the dots from the SQL query, such as request and job ids for
+application logs, account and tenant identifiers, etc.
 
 ### Tagged Logging