query_owl 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a44534cc84c3ea8089418405a3291098f3c35fb6ee3cb6b67d1ebea3cce4a62
-  data.tar.gz: 40272edc4665655ae1fda469819eab1158951fc4a75ea6e417132d5ae80c6103
+  metadata.gz: 5db617fa85bce1a43d851809139bd43015afd92263bd203ac0114921dd94c525
+  data.tar.gz: 4ebf287c62f2779448c2277d416147d7b426332a2dd927f6a1a8485498c76638
 SHA512:
-  metadata.gz: 8f97a828e36d1fe5a8acee9e6dc42198895e12a92a63d02dfb0b91aa35541a5062d5e439ef4035b0ca486655c2e0ea90fbe5efd31eaa8eb93c3b7d26d3184cc6
-  data.tar.gz: 943ad7e59234e171da3831b3b4bfbdd9f43668d413cbd17efba1803f4b225e198d7e047723c4c987c6b85720ad1fc13f1574a210b31c38e6e6f051cc6a3f7c1d
+  metadata.gz: e3ec2642c611837a83dc96fdf8fc7eb669a99c6ae140fc3ad5bb1439a5b2db4349a9038a87a4af8e61fe1156e2d6fcbe43535641a2c51dd3bbcc41f9652ec88c
+  data.tar.gz: 2b2fe57db0a34c3289ef76a6170c4ea0d36d441eb733571ce87d8b506e1772b54d1e63841a8719d009a7ffd52a708b8ce5ad19c36e22839ceb3d33111700ae8b

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/query_owl/configuration.rb

@@ -5,7 +5,7 @@ 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
 
     def initialize
       @enabled                 = Rails.env.development?
@@ -15,6 +15,8 @@ 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?
     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/middleware.rb

@@ -25,6 +25,7 @@ module QueryOwl
                     Detector.detect_unused_eager_loads(eager_data)
       Logger.log_events(events)
       Logger.log_summary(events)
+      events.each { |e| EventStore.push(e) }
       raise_on_n_plus_one!(events) if QueryOwl.config.raise_on_n_plus_one
     end
   end

data/lib/query_owl/version.rb

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

data/lib/query_owl.rb

@@ -2,6 +2,7 @@ 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/middleware"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: query_owl
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -34,16 +34,25 @@ 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/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/logger.rb
 - lib/query_owl/middleware.rb
 - lib/query_owl/query_tracker.rb