query_owl 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a44534cc84c3ea8089418405a3291098f3c35fb6ee3cb6b67d1ebea3cce4a62
-  data.tar.gz: 40272edc4665655ae1fda469819eab1158951fc4a75ea6e417132d5ae80c6103
+  metadata.gz: 9dd0e38c57b1b0c94a99a0ffb22f6ecc71f0e28c6d4d6d041dac57bc6e5bf626
+  data.tar.gz: dd6c94c94314dc38da3a757d0e4147dc349ae8842f10e0e29f9fa7fc2e0727ed
 SHA512:
-  metadata.gz: 8f97a828e36d1fe5a8acee9e6dc42198895e12a92a63d02dfb0b91aa35541a5062d5e439ef4035b0ca486655c2e0ea90fbe5efd31eaa8eb93c3b7d26d3184cc6
-  data.tar.gz: 943ad7e59234e171da3831b3b4bfbdd9f43668d413cbd17efba1803f4b225e198d7e047723c4c987c6b85720ad1fc13f1574a210b31c38e6e6f051cc6a3f7c1d
+  metadata.gz: be09a0350d981ffcd6e2b5b4e57825daf3d4aca7a0747d0f3579188df22ddc5f26babeab619c24e1d47c0e86ebda1dc1dce99ee65ce32cc01ff1cef1f997a95e
+  data.tar.gz: 6d499e2d7972b3252f6eccaae8e415f742e2e28b579c08d9e53f2c7377a998a6c5b7be1a46bc3f4189d353258fe7dc0dd01f5df29eb4986d7851c07ad1179fca

data/README.md

@@ -14,6 +14,7 @@ A leaner alternative to Bullet. QueryOwl detects N+1 queries, slow queries, and
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Log Output](#log-output)
+- [Dashboard Endpoint](#dashboard-endpoint)
 - [Manual Testing in the Dummy App](#manual-testing-in-the-dummy-app)
 - [Roadmap](#roadmap)
 - [Contributing](#contributing)
@@ -67,6 +68,8 @@ QueryOwl.configure do |config|
   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
+  config.event_store_size        = 100   # ring buffer capacity
+  config.dashboard_enabled       = Rails.env.development? # HTML view on/off
 end
 ```
 
@@ -89,6 +92,45 @@ When a problem is detected, QueryOwl writes a structured line to `Rails.logger`:
 
 ---
 
+## Dashboard Endpoint
+
+Mount the engine in your host app's routes to enable the JSON endpoint:
+
+```ruby
+# config/routes.rb
+mount QueryOwl::Engine => "/rails"
+```
+
+Then browse the HTML dashboard or query JSON at `GET /rails/slow_queries`:
+
+```
+GET /rails/slow_queries              # HTML dashboard (browser)
+GET /rails/slow_queries.json         # JSON array
+GET /rails/slow_queries?type=n_plus_one
+GET /rails/slow_queries?type=slow_query
+GET /rails/slow_queries?type=unused_eager_load
+```
+
+The HTML view is enabled when `config.dashboard_enabled` is `true` (default in development); returns `403` otherwise. The JSON endpoint is always available.
+
+The JSON response is an array of event objects, newest first, up to `config.event_store_size` entries:
+
+```json
+[
+  {
+    "type": "n_plus_one",
+    "sql": "SELECT * FROM posts WHERE user_id = ?",
+    "count": 5,
+    "backtrace": ["app/controllers/posts_controller.rb:12"],
+    "recorded_at": "2026-06-15T18:00:00.000Z"
+  }
+]
+```
+
+[↑ 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.

data/app/assets/stylesheets/query_owl/_01_base.css

@@ -0,0 +1,23 @@
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+:root {
+  --bg:      #f8f9fa;
+  --surface: #ffffff;
+  --border:  #dee2e6;
+  --text:    #212529;
+  --muted:   #6c757d;
+  --radius:  6px;
+  --shadow:  0 1px 3px rgba(0,0,0,.08);
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  font-size: 14px;
+  line-height: 1.5;
+  color: var(--text);
+  background: var(--bg);
+  padding: 2rem;
+}
+
+.qo-monospace { font-family: ui-monospace, "SFMono-Regular", Menlo, monospace; font-size: 12px; }
+.qo-muted     { color: var(--muted); font-size: 12px; }

data/app/assets/stylesheets/query_owl/_02_layout.css

@@ -0,0 +1,5 @@
+.qo-header { margin-bottom: 1.5rem; }
+.qo-header h1 { font-size: 1.4rem; font-weight: 600; }
+.qo-header p  { color: var(--muted); margin-top: 0.2rem; }
+
+.qo-empty { color: var(--muted); font-style: italic; margin-top: 1rem; }

data/app/assets/stylesheets/query_owl/_03_table.css

@@ -0,0 +1,29 @@
+.qo-table {
+  width: 100%;
+  border-collapse: collapse;
+  background: var(--surface);
+  border-radius: var(--radius);
+  overflow: hidden;
+  box-shadow: var(--shadow);
+}
+
+.qo-table th {
+  text-align: left;
+  padding: 0.6rem 1rem;
+  background: #f0f0f0;
+  font-weight: 600;
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: .04em;
+  color: var(--muted);
+  border-bottom: 1px solid var(--border);
+}
+
+.qo-table td {
+  padding: 0.6rem 1rem;
+  border-bottom: 1px solid #eee;
+  vertical-align: top;
+}
+
+.qo-table tr:last-child td { border-bottom: none; }
+.qo-table tr:hover td      { background: #fafafa; }

data/app/assets/stylesheets/query_owl/_04_badges.css

@@ -0,0 +1,13 @@
+.qo-badge {
+  display: inline-block;
+  padding: 2px 8px;
+  border-radius: 3px;
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  white-space: nowrap;
+}
+
+.qo-badge--n_plus_one       { background: #fde8e8; color: #c0392b; }
+.qo-badge--slow_query       { background: #fef3e2; color: #e67e22; }
+.qo-badge--unused_eager_load { background: #e8f4fd; color: #2980b9; }

data/app/controllers/query_owl/slow_queries_controller.rb

@@ -0,0 +1,28 @@
+module QueryOwl
+  class SlowQueriesController < ActionController::Base
+    protect_from_forgery with: :null_session
+    layout "query_owl/application"
+    helper QueryOwl::ApplicationHelper
+
+    before_action :check_dashboard_enabled, if: -> { request.format.html? }
+
+    def index
+      filters = request.query_parameters
+      events  = EventStore.all
+      events  = events.select { |e| e[:type].to_s == filters["type"] }       if filters["type"].present?
+      events  = events.select { |e| e[:controller] == filters["controller"] } if filters["controller"].present?
+      events  = events.select { |e| e[:action] == filters["action"] }         if filters["action"].present?
+
+      respond_to do |format|
+        format.json { render json: events }
+        format.html { @events = events.reverse }
+      end
+    end
+
+    private
+
+    def check_dashboard_enabled
+      head :forbidden unless QueryOwl.config.dashboard_enabled
+    end
+  end
+end

data/app/helpers/query_owl/application_helper.rb

@@ -0,0 +1,9 @@
+module QueryOwl
+  module ApplicationHelper
+    def inline_styles
+      dir = QueryOwl::Engine.root.join("app/assets/stylesheets/query_owl")
+      css = dir.glob("_*.css").sort.map(&:read).join("\n")
+      content_tag(:style, css.html_safe)
+    end
+  end
+end

data/app/views/layouts/query_owl/application.html.erb

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>QueryOwl</title>
+  <link rel="icon" href="data:,">
+  <%= inline_styles %>
+</head>
+<body>
+  <%= yield %>
+</body>
+</html>

data/app/views/query_owl/slow_queries/index.html.erb

@@ -0,0 +1,34 @@
+<div class="qo-header">
+  <h1>QueryOwl</h1>
+  <p>Last <%= @events.length %> detected event<%= "s" unless @events.length == 1 %> (newest first)</p>
+</div>
+
+<% if @events.empty? %>
+  <p class="qo-empty">No events detected yet.</p>
+<% else %>
+  <table class="qo-table">
+    <thead>
+      <tr>
+        <th>Type</th>
+        <th>SQL / Details</th>
+        <th>Info</th>
+        <th>Recorded At</th>
+        <th>Backtrace</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @events.each do |event| %>
+        <tr>
+          <td><span class="qo-badge qo-badge--<%= event[:type] %>"><%= event[:type].to_s.tr("_", " ") %></span></td>
+          <td class="qo-monospace"><%= event[:sql] || "#{event[:model]}##{event[:association]}" %></td>
+          <td class="qo-muted">
+            <% if event[:count] %>count: <%= event[:count] %><% end %>
+            <% if event[:duration_ms] %><%= event[:duration_ms] %>ms<% end %>
+          </td>
+          <td class="qo-muted"><%= event[:recorded_at]&.strftime("%H:%M:%S") %></td>
+          <td class="qo-monospace qo-muted"><%= Array(event[:backtrace]).first %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+<% end %>

data/config/routes.rb

@@ -1,2 +1,3 @@
 QueryOwl::Engine.routes.draw do
+  get "slow_queries", to: "slow_queries#index"
 end

data/lib/generators/query_owl/install/install_generator.rb

@@ -0,0 +1,15 @@
+require "rails/generators"
+
+module QueryOwl
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a QueryOwl initializer in config/initializers."
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/query_owl.rb"
+      end
+    end
+  end
+end

data/lib/generators/query_owl/install/templates/initializer.rb

@@ -0,0 +1,42 @@
+QueryOwl.configure do |config|
+  # Enable or disable all QueryOwl tracking.
+  # Defaults to true in development, false elsewhere.
+  # config.enabled = Rails.env.development?
+
+  # Flag N+1 queries when the same SQL pattern fires this many times per request.
+  # config.n_plus_one_threshold = 2
+
+  # Flag individual queries that take longer than this (in milliseconds).
+  # config.slow_query_threshold_ms = 100
+
+  # Log level for QueryOwl warnings (:debug, :info, or :warn).
+  # config.log_level = :warn
+
+  # Number of backtrace frames captured per query.
+  # config.backtrace_lines = 5
+
+  # Custom backtrace filter — a callable that receives a line and returns true to keep it.
+  # Defaults to stripping gem paths and QueryOwl internals.
+  # config.backtrace_filter = ->(line) { line.start_with?("app/") }
+
+  # Raise QueryOwl::NPlusOneError instead of logging when an N+1 is detected.
+  # Useful in CI test suites where silent warnings are easy to miss.
+  # config.raise_on_n_plus_one = false
+
+  # Maximum number of events retained in the in-memory ring buffer.
+  # config.event_store_size = 100
+
+  # Enable the HTML dashboard at GET /slow_queries (when the engine is mounted).
+  # Defaults to true in development, false elsewhere.
+  # config.dashboard_enabled = Rails.env.development?
+
+  # Append each detected event as a JSON line to this file path.
+  # Disabled by default (nil). Useful for persistence across restarts.
+  # config.log_file = Rails.root.join("log/query_owl.log").to_s
+
+  # Notifiers receive each detected event via #call(event).
+  # Defaults to [QueryOwl::Notifiers::Logger] which writes to Rails.logger.
+  # Use Console for TTY-aware colorized output (yellow: N+1, red: slow query).
+  # Use Stdout for non-request contexts (jobs, Rake tasks).
+  # config.notifiers = [QueryOwl::Notifiers::Console.new]
+end

data/lib/query_owl/configuration.rb

@@ -5,7 +5,15 @@ module QueryOwl
 
     attr_reader :log_level, :backtrace_filter
     attr_accessor :enabled, :slow_query_threshold_ms, :n_plus_one_threshold, :backtrace_lines,
-                  :raise_on_n_plus_one
+                  :raise_on_n_plus_one, :event_store_size, :dashboard_enabled, :log_file
+
+    def notifiers
+      @notifiers ||= [Notifiers::Logger.new]
+    end
+
+    def notifiers=(arr)
+      @notifiers = arr
+    end
 
     def initialize
       @enabled                 = Rails.env.development?
@@ -15,6 +23,9 @@ module QueryOwl
       @backtrace_lines         = 5
       @backtrace_filter        = DEFAULT_BACKTRACE_FILTER
       @raise_on_n_plus_one     = false
+      @event_store_size        = 100
+      @dashboard_enabled       = Rails.env.development?
+      @log_file                = nil
     end
 
     def log_level=(level)

data/lib/query_owl/event_store.rb

@@ -0,0 +1,59 @@
+module QueryOwl
+  module EventStore
+    class << self
+      def push(event)
+        mutex.synchronize do
+          ensure_buffer_size
+          buffer[@write_pos] = event.merge(recorded_at: Time.now)
+          @write_pos = (@write_pos + 1) % capacity
+          @stored    = [@stored + 1, capacity].min
+        end
+      end
+
+      def all
+        mutex.synchronize do
+          stored = @stored || 0
+          return [] if stored.zero?
+
+          if stored < capacity
+            buffer.first(stored)
+          else
+            buffer[@write_pos..] + buffer[0...@write_pos]
+          end
+        end
+      end
+
+      def clear
+        mutex.synchronize { reset! }
+      end
+
+      def size
+        mutex.synchronize { @stored || 0 }
+      end
+
+      private
+
+      def mutex
+        @mutex ||= Mutex.new
+      end
+
+      def capacity
+        QueryOwl.config.event_store_size
+      end
+
+      def ensure_buffer_size
+        reset! if @write_pos.nil? || @buffer.nil? || @buffer.size != capacity
+      end
+
+      def buffer
+        @buffer ||= Array.new(capacity)
+      end
+
+      def reset!
+        @buffer    = Array.new(capacity)
+        @write_pos = 0
+        @stored    = 0
+      end
+    end
+  end
+end

data/lib/query_owl/file_logger.rb

@@ -0,0 +1,24 @@
+require "json"
+
+module QueryOwl
+  class FileLogger
+    class << self
+      def append(events)
+        return if events.empty?
+
+        path = QueryOwl.config.log_file
+        return unless path
+
+        File.open(path, "a") do |f|
+          events.each { |e| f.puts(JSON.generate(serializable(e))) }
+        end
+      end
+
+      private
+
+        def serializable(event)
+          event.transform_values { |v| v.is_a?(Symbol) ? v.to_s : v }
+        end
+    end
+  end
+end

data/lib/query_owl/middleware.rb

@@ -18,13 +18,20 @@ module QueryOwl
       EagerLoadTracker.start!
       @app.call(env)
     ensure
-      queries     = QueryTracker.stop!
-      eager_data  = EagerLoadTracker.stop!
-      events      = Detector.detect_n_plus_one(queries) +
+      params  = env["action_dispatch.request.path_parameters"] || {}
+      RequestContext.set(controller: params[:controller], action: params[:action], path: env["PATH_INFO"])
+      queries    = QueryTracker.stop!
+      eager_data = EagerLoadTracker.stop!
+      context    = RequestContext.current
+      RequestContext.clear
+      events     = (Detector.detect_n_plus_one(queries) +
                     Detector.detect_slow_queries(queries) +
-                    Detector.detect_unused_eager_loads(eager_data)
-      Logger.log_events(events)
+                    Detector.detect_unused_eager_loads(eager_data))
+                   .map { |e| e.merge(context) }
+      events.each { |event| QueryOwl.config.notifiers.each { |notifier| notifier.call(event) } }
       Logger.log_summary(events)
+      events.each { |e| EventStore.push(e) }
+      FileLogger.append(events)
       raise_on_n_plus_one!(events) if QueryOwl.config.raise_on_n_plus_one
     end
   end

data/lib/query_owl/notifiers/console.rb

@@ -0,0 +1,38 @@
+module QueryOwl
+  module Notifiers
+    class Console
+      YELLOW = "\e[33m"
+      RED    = "\e[31m"
+      RESET  = "\e[0m"
+
+      def call(event)
+        line = format(event)
+        line = apply_color(event[:type], line) if $stdout.tty?
+        $stdout.puts line
+      end
+
+      private
+
+        def format(event)
+          case event[:type]
+          when :n_plus_one
+            "#{QueryOwl::Logger::PREFIX} n_plus_one  #{event[:sql]}  ×#{event[:count]}"
+          when :slow_query
+            "#{QueryOwl::Logger::PREFIX} slow_query  #{event[:sql]}  #{event[:duration_ms]}ms"
+          when :unused_eager_load
+            "#{QueryOwl::Logger::PREFIX} unused_eager_load  #{event[:model]}##{event[:association]}"
+          else
+            "#{QueryOwl::Logger::PREFIX} #{event[:type]}"
+          end
+        end
+
+        def apply_color(type, text)
+          case type
+          when :n_plus_one then "#{YELLOW}#{text}#{RESET}"
+          when :slow_query  then "#{RED}#{text}#{RESET}"
+          else text
+          end
+        end
+    end
+  end
+end

data/lib/query_owl/notifiers/logger.rb

@@ -0,0 +1,9 @@
+module QueryOwl
+  module Notifiers
+    class Logger
+      def call(event)
+        ::Rails.logger.public_send(QueryOwl.config.log_level, "#{QueryOwl::Logger::PREFIX} #{event.to_json}")
+      end
+    end
+  end
+end

data/lib/query_owl/notifiers/stdout.rb

@@ -0,0 +1,9 @@
+module QueryOwl
+  module Notifiers
+    class Stdout
+      def call(event)
+        $stdout.puts "#{QueryOwl::Logger::PREFIX} #{event.to_json}"
+      end
+    end
+  end
+end

data/lib/query_owl/request_context.rb

@@ -0,0 +1,17 @@
+module QueryOwl
+  module RequestContext
+    class << self
+      def set(controller:, action:, path:)
+        Thread.current[:query_owl_request_context] = { controller: controller, action: action, path: path }
+      end
+
+      def current
+        Thread.current[:query_owl_request_context] || {}
+      end
+
+      def clear
+        Thread.current[:query_owl_request_context] = nil
+      end
+    end
+  end
+end

data/lib/query_owl/version.rb

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

data/lib/query_owl.rb

@@ -2,8 +2,14 @@ require "query_owl/version"
 require "query_owl/configuration"
 require "query_owl/query_tracker"
 require "query_owl/eager_load_tracker"
+require "query_owl/event_store"
 require "query_owl/detector"
 require "query_owl/logger"
+require "query_owl/file_logger"
+require "query_owl/notifiers/logger"
+require "query_owl/notifiers/stdout"
+require "query_owl/notifiers/console"
+require "query_owl/request_context"
 require "query_owl/middleware"
 require "query_owl/engine"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: query_owl
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -34,19 +34,35 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- app/assets/stylesheets/query_owl/_01_base.css
+- app/assets/stylesheets/query_owl/_02_layout.css
+- app/assets/stylesheets/query_owl/_03_table.css
+- app/assets/stylesheets/query_owl/_04_badges.css
 - app/controllers/query_owl/application_controller.rb
+- app/controllers/query_owl/slow_queries_controller.rb
+- app/helpers/query_owl/application_helper.rb
 - app/jobs/query_owl/application_job.rb
 - app/mailers/query_owl/application_mailer.rb
 - app/models/query_owl/application_record.rb
+- app/views/layouts/query_owl/application.html.erb
+- app/views/query_owl/slow_queries/index.html.erb
 - config/routes.rb
+- lib/generators/query_owl/install/install_generator.rb
+- lib/generators/query_owl/install/templates/initializer.rb
 - 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/event_store.rb
+- lib/query_owl/file_logger.rb
 - lib/query_owl/logger.rb
 - lib/query_owl/middleware.rb
+- lib/query_owl/notifiers/console.rb
+- lib/query_owl/notifiers/logger.rb
+- lib/query_owl/notifiers/stdout.rb
 - lib/query_owl/query_tracker.rb
+- lib/query_owl/request_context.rb
 - lib/query_owl/version.rb
 - lib/tasks/query_owl_tasks.rake
 homepage: https://github.com/eclectic-coding/query_owl