query_owl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 45b067e5caa42b01df6cb84cce7541b77ee9bbee1f9f6d919ed554fb2386fd0e
+  data.tar.gz: 688d0b4f41edcf13e99bad7dbe6a4bdfe8ad40d458f908a06c2bc87b8ccbdbea
+SHA512:
+  metadata.gz: 960d4332a40bd8531ccdda7b06d8e6a947b048c3c5f758fba374e62759668bbe43ae335e7d5dc4fc394785e2ea5fa6e13e1f7f8ca9c4e6f035f52b380815c982
+  data.tar.gz: 1764fbd57f9359a30866c2665a5698ede5bd4764fab90f10afa7984451086cc1d51fd8bf933828bfdff14a87631c753824b8cff7cd225a1474ca41b9efd5a0f3

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Chuck Smith
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,165 @@
+# QueryOwl
+
+[![CI](https://github.com/eclectic-coding/query_owl/actions/workflows/main.yml/badge.svg)](https://github.com/eclectic-coding/query_owl/actions/workflows/main.yml)
+[![Gem Version](https://img.shields.io/gem/v/query_owl)](https://rubygems.org/gems/query_owl)
+[![Downloads](https://img.shields.io/gem/dt/query_owl)](https://rubygems.org/gems/query_owl)
+[![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.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Log Output](#log-output)
+- [Manual Testing in the Dummy App](#manual-testing-in-the-dummy-app)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Features
+
+- **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)
+- **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
+
+[↑ Back to top](#table-of-contents)
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "query_owl"
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+[↑ Back to top](#table-of-contents)
+
+---
+
+## Configuration
+
+Create an initializer:
+
+```ruby
+# config/initializers/query_owl.rb
+QueryOwl.configure do |config|
+  config.enabled                 = Rails.env.development?
+  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
+end
+```
+
+[↑ Back to top](#table-of-contents)
+
+---
+
+## Log Output
+
+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}
+```
+
+[↑ Back to top](#table-of-contents)
+
+---
+
+## Manual Testing in the Dummy App
+
+The gem ships with a minimal Rails app in `spec/dummy/` for manual verification.
+
+**Start a console:**
+
+```sh
+cd spec/dummy
+RAILS_ENV=development bin/rails console
+```
+
+**Trigger N+1 detection:**
+
+```ruby
+QueryOwl.config.enabled = true
+QueryOwl::QueryTracker.start!
+Widget.all.each { |w| Widget.find(w.id) }
+queries = QueryOwl::QueryTracker.stop!
+events  = QueryOwl::Detector.detect_n_plus_one(queries)
+QueryOwl::Logger.log_events(events)
+# => [QueryOwl] {"type":"n_plus_one","sql":"SELECT ...","count":3,...}
+```
+
+**Trigger slow query detection:**
+
+```ruby
+QueryOwl.config.slow_query_threshold_ms = 0  # flag everything
+QueryOwl::QueryTracker.start!
+Widget.all.to_a
+queries = QueryOwl::QueryTracker.stop!
+events  = QueryOwl::Detector.detect_slow_queries(queries)
+QueryOwl::Logger.log_events(events)
+# => [QueryOwl] {"type":"slow_query","sql":"SELECT ...","duration_ms":...}
+```
+
+**Full pipeline** (as it runs on every real HTTP request):
+
+```ruby
+QueryOwl.config.slow_query_threshold_ms = 0
+QueryOwl::QueryTracker.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)
+QueryOwl::Logger.log_events(events)
+```
+
+**Seed the dummy database first** (if needed):
+
+```sh
+cd spec/dummy
+RAILS_ENV=development bin/rails db:migrate
+RAILS_ENV=development bin/rails runner "3.times { |i| Widget.create!(name: \"Widget #{i}\") }"
+```
+
+[↑ Back to top](#table-of-contents)
+
+---
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md) for planned releases, including unused eager load detection (0.2.0) and a `/rails/slow_queries` dashboard endpoint (0.3.0).
+
+[↑ Back to top](#table-of-contents)
+
+---
+
+## Contributing
+
+1. Fork the repo and create a `feat/<name>` branch
+2. Write specs for your change
+3. Run `bundle exec rake` (lint + audit + tests) before opening a PR
+
+[↑ Back to top](#table-of-contents)
+
+---
+
+## License
+
+MIT — see [MIT-LICENSE](MIT-LICENSE).
+
+[↑ Back to top](#table-of-contents)

data/Rakefile

@@ -0,0 +1,20 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+require 'rubocop/rake_task'
+require 'bundler/audit/task'
+require 'rspec/core/rake_task'
+
+RuboCop::RakeTask.new(:lint)
+Bundler::Audit::Task.new
+RSpec::Core::RakeTask.new(:spec)
+
+task default: [:lint, :'bundle:audit:update', 'bundle:audit:check', :spec]
+
+desc "Run performance benchmarks"
+task :benchmark do
+  ruby "benchmarks/benchmark.rb"
+end

data/app/controllers/query_owl/application_controller.rb

@@ -0,0 +1,4 @@
+module QueryOwl
+  class ApplicationController < ActionController::API
+  end
+end

data/app/jobs/query_owl/application_job.rb

@@ -0,0 +1,4 @@
+module QueryOwl
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/query_owl/application_mailer.rb

@@ -0,0 +1,6 @@
+module QueryOwl
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/query_owl/application_record.rb

@@ -0,0 +1,5 @@
+module QueryOwl
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/config/routes.rb

@@ -0,0 +1,2 @@
+QueryOwl::Engine.routes.draw do
+end

data/lib/query_owl/configuration.rb

@@ -0,0 +1,23 @@
+module QueryOwl
+  class Configuration
+    VALID_LOG_LEVELS = %i[debug info warn].freeze
+
+    attr_reader :log_level
+    attr_accessor :enabled, :slow_query_threshold_ms, :n_plus_one_threshold
+
+    def initialize
+      @enabled                = Rails.env.development?
+      @slow_query_threshold_ms = 100
+      @n_plus_one_threshold   = 2
+      @log_level              = :warn
+    end
+
+    def log_level=(level)
+      unless VALID_LOG_LEVELS.include?(level)
+        raise ArgumentError, "log_level must be one of #{VALID_LOG_LEVELS.inspect}"
+      end
+
+      @log_level = level
+    end
+  end
+end

data/lib/query_owl/detector.rb

@@ -0,0 +1,52 @@
+module QueryOwl
+  module Detector
+    # Matches numeric literals, single-quoted strings, and IN-list contents.
+    NORMALIZE_PATTERNS = [
+      [/'[^']*'/, "?"],
+      [/\b\d+\b/, "?"],
+      [/\s+/, " "]
+    ].freeze
+
+    class << self
+      def detect_n_plus_one(queries)
+        threshold = QueryOwl.config.n_plus_one_threshold
+
+        queries
+          .reject { |q| q[:cached] }
+          .group_by { |q| normalize(q[:sql]) }
+          .filter_map do |normalized_sql, group|
+            next if group.length < threshold
+
+            {
+              type: :n_plus_one,
+              sql: normalized_sql,
+              count: group.length,
+              backtrace: group.first[:backtrace]
+            }
+          end
+      end
+
+      def detect_slow_queries(queries)
+        threshold = QueryOwl.config.slow_query_threshold_ms
+
+        queries.filter_map do |q|
+          next if q[:cached]
+          next if q[:duration_ms] < threshold
+
+          {
+            type: :slow_query,
+            sql: normalize(q[:sql]),
+            duration_ms: q[:duration_ms],
+            backtrace: q[:backtrace]
+          }
+        end
+      end
+
+      def normalize(sql)
+        NORMALIZE_PATTERNS
+          .reduce(sql.to_s) { |s, (pattern, replacement)| s.gsub(pattern, replacement) }
+          .strip
+      end
+    end
+  end
+end

data/lib/query_owl/engine.rb

@@ -0,0 +1,19 @@
+module QueryOwl
+  class Engine < ::Rails::Engine
+    isolate_namespace QueryOwl
+    config.generators.api_only = true
+
+    initializer "query_owl.subscribe" do
+      ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
+        next unless QueryOwl.config.enabled
+
+        event = ActiveSupport::Notifications::Event.new(*args)
+        QueryTracker.record(event)
+      end
+    end
+
+    initializer "query_owl.request_tracking" do |app|
+      app.middleware.use(Middleware)
+    end
+  end
+end

data/lib/query_owl/logger.rb

@@ -0,0 +1,21 @@
+require "json"
+
+module QueryOwl
+  module Logger
+    PREFIX = "[QueryOwl]"
+
+    class << self
+      def log_events(events)
+        return if events.empty?
+
+        events.each { |event| write(event) }
+      end
+
+      private
+
+      def write(event)
+        Rails.logger.public_send(QueryOwl.config.log_level, "#{PREFIX} #{event.to_json}")
+      end
+    end
+  end
+end

data/lib/query_owl/middleware.rb

@@ -0,0 +1,18 @@
+module QueryOwl
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      return @app.call(env) unless QueryOwl.config.enabled
+
+      QueryTracker.start!
+      @app.call(env)
+    ensure
+      queries = QueryTracker.stop!
+      events  = Detector.detect_n_plus_one(queries) + Detector.detect_slow_queries(queries)
+      Logger.log_events(events)
+    end
+  end
+end

data/lib/query_owl/query_tracker.rb

@@ -0,0 +1,44 @@
+module QueryOwl
+  module QueryTracker
+    IGNORED_PATTERNS = /^(SCHEMA|EXPLAIN|BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE)/i
+
+    class << self
+      def start!
+        Thread.current[:query_owl_queries] = []
+      end
+
+      def record(event)
+        return unless tracking?
+        return if event.payload[:name] == "SCHEMA"
+        return if event.payload[:sql].to_s.match?(IGNORED_PATTERNS)
+
+        queries << {
+          sql: event.payload[:sql],
+          duration_ms: event.duration.round(2),
+          cached: event.payload[:cached],
+          backtrace: filtered_backtrace
+        }
+      end
+
+      def queries
+        Thread.current[:query_owl_queries] ||= []
+      end
+
+      def stop!
+        collected = queries.dup
+        Thread.current[:query_owl_queries] = nil
+        collected
+      end
+
+      def tracking?
+        !Thread.current[:query_owl_queries].nil?
+      end
+
+      private
+
+      def filtered_backtrace
+        caller.grep_v(%r{/gems/|/rubygems/|/ruby/gems/|lib/query_owl/}).first(5)
+      end
+    end
+  end
+end

data/lib/query_owl/version.rb

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

data/lib/query_owl.rb

@@ -0,0 +1,23 @@
+require "query_owl/version"
+require "query_owl/configuration"
+require "query_owl/query_tracker"
+require "query_owl/detector"
+require "query_owl/logger"
+require "query_owl/middleware"
+require "query_owl/engine"
+
+module QueryOwl
+  class << self
+    def configure
+      yield config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def reset_config!
+      @config = Configuration.new
+    end
+  end
+end

data/lib/tasks/query_owl_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :query_owl do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: query_owl
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chuck Smith
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: A leaner alternative to Bullet. Detects N+1 queries and slow queries
+  in development, logging structured warnings to your Rails logger without the noise.
+email:
+- eclectic-coding@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/query_owl/application_controller.rb
+- app/jobs/query_owl/application_job.rb
+- app/mailers/query_owl/application_mailer.rb
+- app/models/query_owl/application_record.rb
+- config/routes.rb
+- lib/query_owl.rb
+- lib/query_owl/configuration.rb
+- lib/query_owl/detector.rb
+- lib/query_owl/engine.rb
+- lib/query_owl/logger.rb
+- lib/query_owl/middleware.rb
+- lib/query_owl/query_tracker.rb
+- lib/query_owl/version.rb
+- lib/tasks/query_owl_tasks.rake
+homepage: https://github.com/eclectic-coding/query_owl
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/eclectic-coding/query_owl
+  source_code_uri: https://github.com/eclectic-coding/query_owl
+  changelog_uri: https://github.com/eclectic-coding/query_owl/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Structured N+1 and slow query warnings for Rails development.
+test_files: []