query_owl 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45b067e5caa42b01df6cb84cce7541b77ee9bbee1f9f6d919ed554fb2386fd0e
-  data.tar.gz: 688d0b4f41edcf13e99bad7dbe6a4bdfe8ad40d458f908a06c2bc87b8ccbdbea
+  metadata.gz: 6a44534cc84c3ea8089418405a3291098f3c35fb6ee3cb6b67d1ebea3cce4a62
+  data.tar.gz: 40272edc4665655ae1fda469819eab1158951fc4a75ea6e417132d5ae80c6103
 SHA512:
-  metadata.gz: 960d4332a40bd8531ccdda7b06d8e6a947b048c3c5f758fba374e62759668bbe43ae335e7d5dc4fc394785e2ea5fa6e13e1f7f8ca9c4e6f035f52b380815c982
-  data.tar.gz: 1764fbd57f9359a30866c2665a5698ede5bd4764fab90f10afa7984451086cc1d51fd8bf933828bfdff14a87631c753824b8cff7cd225a1474ca41b9efd5a0f3
+  metadata.gz: 8f97a828e36d1fe5a8acee9e6dc42198895e12a92a63d02dfb0b91aa35541a5062d5e439ef4035b0ca486655c2e0ea90fbe5efd31eaa8eb93c3b7d26d3184cc6
+  data.tar.gz: 943ad7e59234e171da3831b3b4bfbdd9f43668d413cbd17efba1803f4b225e198d7e047723c4c987c6b85720ad1fc13f1574a210b31c38e6e6f051cc6a3f7c1d

data/README.md

@@ -6,7 +6,7 @@
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-ruby)](https://www.ruby-lang.org)
 [![codecov](https://codecov.io/gh/eclectic-coding/query_owl/branch/main/graph/badge.svg)](https://codecov.io/gh/eclectic-coding/query_owl)
 
-A leaner alternative to Bullet. QueryOwl detects N+1 queries and slow queries in development, logging structured warnings to your Rails logger — without the noise.
+A leaner alternative to Bullet. QueryOwl detects N+1 queries, slow queries, and unused eager loads in development, logging structured warnings to your Rails logger — without the noise.
 
 ## Table of Contents
 
@@ -25,6 +25,9 @@ A leaner alternative to Bullet. QueryOwl detects N+1 queries and slow queries in
 
 - **N+1 detection** — flags when the same SQL pattern fires 2+ times in a single request
 - **Slow query detection** — flags queries exceeding a configurable threshold (default: 100ms)
+- **Unused eager load detection** — flags associations preloaded via `includes`/`eager_load` that are never accessed during the request
+- **Per-request summary** — single summary line at the end of each request with totals (e.g. `Request complete — 3 N+1s, 1 slow query`)
+- **CI-friendly raise mode** — set `raise_on_n_plus_one: true` to raise `QueryOwl::NPlusOneError` instead of logging, making N+1s fail fast in test suites
 - **Structured log output** — JSON-style warnings via `Rails.logger` with SQL, duration, count, and filtered backtrace
 - **Zero overhead in production** — auto-enabled in development only
 
@@ -61,6 +64,9 @@ QueryOwl.configure do |config|
   config.slow_query_threshold_ms = 100   # flag queries slower than this
   config.n_plus_one_threshold    = 2     # flag after this many repeated patterns
   config.log_level               = :warn # :warn | :info | :debug
+  config.backtrace_lines         = 5     # number of backtrace frames to capture
+  config.backtrace_filter        = ->(line) { line.start_with?("app/") } # optional custom filter
+  config.raise_on_n_plus_one     = false # set true in CI to raise instead of log
 end
 ```
 
@@ -75,6 +81,8 @@ When a problem is detected, QueryOwl writes a structured line to `Rails.logger`:
 ```
 [QueryOwl] {"type":"n_plus_one","sql":"SELECT * FROM posts WHERE user_id = ?","count":10,"backtrace":["app/controllers/posts_controller.rb:12"]}
 [QueryOwl] {"type":"slow_query","sql":"SELECT * FROM reports WHERE ...","duration_ms":340}
+[QueryOwl] {"type":"unused_eager_load","model":"Widget","association":"tags"}
+[QueryOwl] Request complete — 10 N+1s, 1 slow query, 1 unused eager load
 ```
 
 [↑ Back to top](#table-of-contents)
@@ -116,15 +124,30 @@ QueryOwl::Logger.log_events(events)
 # => [QueryOwl] {"type":"slow_query","sql":"SELECT ...","duration_ms":...}
 ```
 
+**Trigger unused eager load detection:**
+
+```ruby
+QueryOwl.config.enabled = true
+QueryOwl::EagerLoadTracker.start!
+Widget.includes(:tags).map(&:name)   # loads tags but never touches them
+eager_data = QueryOwl::EagerLoadTracker.stop!
+events = QueryOwl::Detector.detect_unused_eager_loads(eager_data)
+QueryOwl::Logger.log_events(events)
+# => [QueryOwl] {"type":"unused_eager_load","model":"Widget","association":"tags"}
+```
+
 **Full pipeline** (as it runs on every real HTTP request):
 
 ```ruby
 QueryOwl.config.slow_query_threshold_ms = 0
 QueryOwl::QueryTracker.start!
+QueryOwl::EagerLoadTracker.start!
 Widget.all.each { |w| Widget.find(w.id) }
-queries = QueryOwl::QueryTracker.stop!
-events  = QueryOwl::Detector.detect_n_plus_one(queries) +
-          QueryOwl::Detector.detect_slow_queries(queries)
+queries    = QueryOwl::QueryTracker.stop!
+eager_data = QueryOwl::EagerLoadTracker.stop!
+events     = QueryOwl::Detector.detect_n_plus_one(queries) +
+             QueryOwl::Detector.detect_slow_queries(queries) +
+             QueryOwl::Detector.detect_unused_eager_loads(eager_data)
 QueryOwl::Logger.log_events(events)
 ```
 

data/lib/query_owl/configuration.rb

@@ -1,15 +1,20 @@
 module QueryOwl
   class Configuration
     VALID_LOG_LEVELS = %i[debug info warn].freeze
+    DEFAULT_BACKTRACE_FILTER = ->(line) { line !~ %r{/gems/|/rubygems/|/ruby/gems/|lib/query_owl/} }
 
-    attr_reader :log_level
-    attr_accessor :enabled, :slow_query_threshold_ms, :n_plus_one_threshold
+    attr_reader :log_level, :backtrace_filter
+    attr_accessor :enabled, :slow_query_threshold_ms, :n_plus_one_threshold, :backtrace_lines,
+                  :raise_on_n_plus_one
 
     def initialize
-      @enabled                = Rails.env.development?
+      @enabled                 = Rails.env.development?
       @slow_query_threshold_ms = 100
-      @n_plus_one_threshold   = 2
-      @log_level              = :warn
+      @n_plus_one_threshold    = 2
+      @log_level               = :warn
+      @backtrace_lines         = 5
+      @backtrace_filter        = DEFAULT_BACKTRACE_FILTER
+      @raise_on_n_plus_one     = false
     end
 
     def log_level=(level)
@@ -19,5 +24,11 @@ module QueryOwl
 
       @log_level = level
     end
+
+    def backtrace_filter=(filter)
+      raise ArgumentError, "backtrace_filter must respond to #call" unless filter.respond_to?(:call)
+
+      @backtrace_filter = filter
+    end
   end
 end

data/lib/query_owl/detector.rb

@@ -1,9 +1,13 @@
 module QueryOwl
   module Detector
-    # Matches numeric literals, single-quoted strings, and IN-list contents.
     NORMALIZE_PATTERNS = [
       [/'[^']*'/, "?"],
-      [/\b\d+\b/, "?"],
+      [/\b[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\b/i, "?"],
+      [/\$\d+/, "?"],
+      [/\b\d+\.?\d*\b/, "?"],
+      [/\bIN\s*\(\s*\?(?:\s*,\s*\?)*\s*\)/i, "IN (?)"],
+      [/"([^"]+)"/, '\1'],
+      [/`([^`]+)`/, '\1'],
       [/\s+/, " "]
     ].freeze
 
@@ -42,6 +46,16 @@ module QueryOwl
         end
       end
 
+      def detect_unused_eager_loads(eager_data)
+        preloaded = eager_data[:preloaded] || []
+        accessed  = eager_data[:accessed]  || Set.new
+
+        preloaded
+          .uniq { |e| "#{e[:model]}##{e[:association]}" }
+          .reject { |e| accessed.include?("#{e[:model]}##{e[:association]}") }
+          .map { |e| { type: :unused_eager_load, model: e[:model], association: e[:association] } }
+      end
+
       def normalize(sql)
         NORMALIZE_PATTERNS
           .reduce(sql.to_s) { |s, (pattern, replacement)| s.gsub(pattern, replacement) }

data/lib/query_owl/eager_load_tracker.rb

@@ -0,0 +1,43 @@
+module QueryOwl
+  module EagerLoadTracker
+    class << self
+      def start!
+        Thread.current[:query_owl_preloaded] = []
+        Thread.current[:query_owl_el_accessed] = Set.new
+      end
+
+      def stop!
+        result = { preloaded: preloaded.dup, accessed: accessed.dup }
+        Thread.current[:query_owl_preloaded] = nil
+        Thread.current[:query_owl_el_accessed] = nil
+        result
+      end
+
+      def tracking?
+        !Thread.current[:query_owl_preloaded].nil?
+      end
+
+      def record_preload(model_name, association_name)
+        return unless tracking?
+
+        preloaded << { model: model_name.to_s, association: association_name.to_s }
+      end
+
+      def record_access(model_name, association_name)
+        return unless tracking?
+
+        accessed << "#{model_name}##{association_name}"
+      end
+
+      private
+
+      def preloaded
+        Thread.current[:query_owl_preloaded] ||= []
+      end
+
+      def accessed
+        Thread.current[:query_owl_el_accessed] ||= Set.new
+      end
+    end
+  end
+end

data/lib/query_owl/engine.rb

@@ -15,5 +15,35 @@ module QueryOwl
     initializer "query_owl.request_tracking" do |app|
       app.middleware.use(Middleware)
     end
+
+    config.after_initialize do
+      ActiveRecord::Associations::Preloader.prepend(Module.new do
+        def initialize(records:, associations:, **kwargs)
+          if QueryOwl::EagerLoadTracker.tracking? && records.any?
+            model_name = records.first.class.name
+            Array(associations).each do |assoc|
+              QueryOwl::EagerLoadTracker.record_preload(model_name, assoc)
+            end
+          end
+          super
+        end
+
+        def call
+          Thread.current[:query_owl_preloading] = true
+          super
+        ensure
+          Thread.current[:query_owl_preloading] = false
+        end
+      end)
+
+      ActiveRecord::Base.prepend(Module.new do
+        def association(name)
+          unless Thread.current[:query_owl_preloading]
+            QueryOwl::EagerLoadTracker.record_access(self.class.name, name)
+          end
+          super
+        end
+      end)
+    end
   end
 end

data/lib/query_owl/logger.rb

@@ -11,6 +11,18 @@ module QueryOwl
         events.each { |event| write(event) }
       end
 
+      def log_summary(events)
+        return if events.empty?
+
+        counts = events.group_by { |e| e[:type] }.transform_values(&:count)
+        parts  = []
+        parts << "#{counts[:n_plus_one]} N+1#{"s" if counts[:n_plus_one] != 1}" if counts[:n_plus_one]
+        parts << "#{counts[:slow_query]} slow #{counts[:slow_query] == 1 ? "query" : "queries"}" if counts[:slow_query]
+        parts << "#{counts[:unused_eager_load]} unused eager load#{"s" if counts[:unused_eager_load] != 1}" if counts[:unused_eager_load]
+
+        Rails.logger.public_send(QueryOwl.config.log_level, "#{PREFIX} Request complete — #{parts.join(", ")}")
+      end
+
       private
 
       def write(event)

data/lib/query_owl/middleware.rb

@@ -4,15 +4,28 @@ module QueryOwl
       @app = app
     end
 
+    def raise_on_n_plus_one!(events)
+      event = events.find { |e| e[:type] == :n_plus_one }
+      return unless event
+
+      raise NPlusOneError, "N+1 detected: #{event[:sql]} (#{event[:count]} times) #{event[:backtrace].first}"
+    end
+
     def call(env)
       return @app.call(env) unless QueryOwl.config.enabled
 
       QueryTracker.start!
+      EagerLoadTracker.start!
       @app.call(env)
     ensure
-      queries = QueryTracker.stop!
-      events  = Detector.detect_n_plus_one(queries) + Detector.detect_slow_queries(queries)
+      queries     = QueryTracker.stop!
+      eager_data  = EagerLoadTracker.stop!
+      events      = Detector.detect_n_plus_one(queries) +
+                    Detector.detect_slow_queries(queries) +
+                    Detector.detect_unused_eager_loads(eager_data)
       Logger.log_events(events)
+      Logger.log_summary(events)
+      raise_on_n_plus_one!(events) if QueryOwl.config.raise_on_n_plus_one
     end
   end
 end

data/lib/query_owl/query_tracker.rb

@@ -37,7 +37,9 @@ module QueryOwl
       private
 
       def filtered_backtrace
-        caller.grep_v(%r{/gems/|/rubygems/|/ruby/gems/|lib/query_owl/}).first(5)
+        filter = QueryOwl.config.backtrace_filter
+        lines  = QueryOwl.config.backtrace_lines
+        caller.select { |line| filter.call(line) }.first(lines)
       end
     end
   end

data/lib/query_owl/version.rb

@@ -1,3 +1,3 @@
 module QueryOwl
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/query_owl.rb

@@ -1,12 +1,15 @@
 require "query_owl/version"
 require "query_owl/configuration"
 require "query_owl/query_tracker"
+require "query_owl/eager_load_tracker"
 require "query_owl/detector"
 require "query_owl/logger"
 require "query_owl/middleware"
 require "query_owl/engine"
 
 module QueryOwl
+  class NPlusOneError < StandardError; end
+
   class << self
     def configure
       yield config

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: query_owl
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -42,6 +42,7 @@ files:
 - lib/query_owl.rb
 - lib/query_owl/configuration.rb
 - lib/query_owl/detector.rb
+- lib/query_owl/eager_load_tracker.rb
 - lib/query_owl/engine.rb
 - lib/query_owl/logger.rb
 - lib/query_owl/middleware.rb