Update doc/development/query_recorder.md

doc/development/query_recorder.md

@@ -45,17 +45,41 @@ This could lead to false successes where subsequent "requests" could have querie
 
 ## Finding the source of the query
 
-It may be useful to identify the source of the queries by looking at the call backtrace.
-To enable this, run the specs with the `QUERY_RECORDER_DEBUG` environment variable set. For example:
+There are multiple ways to find the source of queries.
 
-```shell
-QUERY_RECORDER_DEBUG=1 bundle exec rspec spec/requests/api/projects_spec.rb
-```
+1. The `QueryRecorder` `data` attribute stores queries by `file_name:line_number:method_name`.
+   Each entry is a `hash` with the following fields:
+
+   - `count`: the number of times a query from this `file_name:line_number:method_name` was called
+   - `occurrences`: the actual `SQL` of each call
+   - `backtrace`: the stack trace of each call (if either of the two following options were enabled)
+
+   `QueryRecorder#find_query` allows filtering queries by their `file_name:line_number:method_name` and
+   `count` attributes. For example:
+
+   ```ruby
+   control = ActiveRecord::QueryRecorder.new(skip_cached: false) { visit_some_page }
+   control.find_query(/.*note.rb.*/, 0, first_only: true)
+   ```
+
+   `QueryRecorder#occurrences_by_line_method` returns a sorted array based on `data`, sorted by `count`.
 
-This will log calls to QueryRecorder into the `test.log`. For example:
+1. You can output the call backtrace for the specific `QueryRecorder` instance you want
+   by using `ActiveRecord::QueryRecorder.new(query_recorder_debug: true)`.  The output
+   will be in `test.log`
 
-```plaintext
-QueryRecorder SQL: SELECT COUNT(*) FROM "issues" WHERE "issues"."deleted_at" IS NULL AND "issues"."project_id" = $1 AND ("issues"."state" IN ('opened')) AND "issues"."confidential" = $2
+1. Using the environment variable `QUERY_RECORDER_DEBUG`, the call backtrace will be output for all tests.
+
+   To enable this, run the specs with the `QUERY_RECORDER_DEBUG` environment variable set. For example:
+
+   ```shell
+   QUERY_RECORDER_DEBUG=1 bundle exec rspec spec/requests/api/projects_spec.rb
+   ```
+
+   This will log calls to QueryRecorder into the `test.log` file. For example:
+
+   ```plaintext
+    QueryRecorder SQL: SELECT COUNT(*) FROM "issues" WHERE "issues"."deleted_at" IS NULL AND "issues"."project_id" = $1 AND ("issues"."state" IN ('opened')) AND "issues"."confidential" = $2
        --> /home/user/gitlab/gdk/gitlab/spec/support/query_recorder.rb:19:in `callback'
        --> /home/user/.rbenv/versions/2.3.5/lib/ruby/gems/2.3.0/gems/activesupport-4.2.8/lib/active_support/notifications/fanout.rb:127:in `finish'
        --> /home/user/.rbenv/versions/2.3.5/lib/ruby/gems/2.3.0/gems/activesupport-4.2.8/lib/active_support/notifications/fanout.rb:46:in `block in finish'
@@ -87,7 +111,7 @@ QueryRecorder SQL: SELECT COUNT(*) FROM "issues" WHERE "issues"."deleted_at" IS
        --> /home/user/.rbenv/versions/2.3.5/lib/ruby/gems/2.3.0/gems/activesupport-4.2.8/lib/active_support/cache.rb:299:in `fetch'
        --> /home/user/gitlab/gdk/gitlab/app/services/base_count_service.rb:12:in `count'
        --> /home/user/gitlab/gdk/gitlab/app/models/project.rb:1296:in `open_issues_count'
-```
+   ```
 
 ## See also