rails_vitals 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f17a9a533950167bfbd68780d388d56e95ec38fb442958ddf7228d323190eb24
+  data.tar.gz: 165535e4b833e3f622965142d6605a7423a85a0a607131eed1a3240c4cea8fe7
+SHA512:
+  metadata.gz: 0d7b5af657229031b4189605e661028ccda2f169f585acc48188d7a34a22aa0ed7422bee6291b79edf52d7cee46aedc403c0a823fa8c1f6139a4925b8a4dd4dc
+  data.tar.gz: 49d029d3b489e21656b1f750066d759611785b077f9e32c1a42a2d2d784c2abe3efa31728100250d17c651f765072b11cf9c151bdb9998f06d6677bc5752dd05

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright David Sanchez
+
+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,340 @@
+# ⚡ RailsVitals
+
+> **The Rails gem that made me understand performance.**
+
+RailsVitals is a zero-dependency Rails Engine that instruments every request in your app and surfaces performance diagnostics: N+1 queries, slow SQL, fat callbacks, and health scores through an embedded admin UI and an injectable panel overlay.
+
+It doesn't just tell you something is wrong. It shows you **why**, **where**, and **what to do about it**.
+
+---
+
+## Screenshots
+
+![RailsVitals Dashboard](https://github.com/user-attachments/assets/caa21065-5929-4c3a-9dbe-34fb01799817)
+
+> Full admin UI at `/rails_vitals` with Dashboard, Request History,
+> Request Detail with Query DNA, Endpoint Heatmap, Per-Model Breakdown,
+> N+1 Patterns and Association Map.
+
+---
+
+## Features
+
+### 🔴 Per-Request Health Score
+Every request gets a score from 0–100 based on query volume and N+1 severity. Scores are color-coded: Healthy (90–100), Acceptable (70–89), Warning (50–69), Critical (0–49).
+
+![Health Score](https://github.com/user-attachments/assets/3e10b4ea-556e-4d51-b32b-f8bb6f9a267b)
+
+### 🧬 Query DNA — Visual SQL Fingerprinting
+Every query in a request is decomposed into color-coded tokens: `SELECT *`, `WHERE fk =`, `IN (...)`, `JOIN`, `ORDER BY`, `OFFSET`, and more. Click any query to expand its DNA. Click any token to read an education card explaining what it means, why it matters, and how to fix it.
+
+![Query DNA](https://github.com/user-attachments/assets/08857413-4759-460c-ada4-1813ca462baf)
+
+### 🗺️ Association Map
+A live SVG diagram of your ActiveRecord model graph, annotated with N+1 status, query counts, average query time, foreign key names, and index status on every edge. Nodes light up red when N+1 patterns are detected. Dashed edges signal missing indexes on foreign keys. Click any node to open a detail panel with fix suggestions and links to affected requests.
+
+![Association Map](https://github.com/user-attachments/assets/7a984138-f436-44f6-b586-b54e02208a7c)
+
+### 🔥 Endpoint Heatmap
+A ranked table of every endpoint in your app sorted by worst average health score. Columns: average score, hit count, average query count, average DB time, average callback time, N+1 frequency. The worst offenders surface immediately.
+
+![Endpoint Heatmap](https://github.com/user-attachments/assets/7503f788-e5f7-4ec4-92b2-4f6ed3ae3b2d)
+
+### 📊 Per-Model Breakdown
+Which ActiveRecord models are hammering your database? The model breakdown aggregates queries by table, shows total query count, total DB time, average query time, and the endpoints responsible.
+
+![Model Breakdown](https://github.com/user-attachments/assets/deb0e2f8-cc7e-479e-8b0a-43cf5a15a629)
+
+### 🔍 N+1 Pattern Detector
+Cross-request N+1 aggregation using normalized SQL fingerprinting. Each pattern shows total occurrences, affected endpoints, and a concrete fix suggestion generated by reflecting on your actual ActiveRecord associations e.g. `Post.includes(:likes)`, not a generic hint.
+
+![N+1 Pattern Detector](https://github.com/user-attachments/assets/150c3b55-dcb2-48e1-87a7-1471cff3e19c)
+
+
+### 💥 Impact Simulator
+Each N+1 pattern has a detail page showing affected requests, estimated query savings, and a generated migration-ready fix. See the blast radius before you write a line of code.
+
+![Impact Simulator](https://github.com/user-attachments/assets/c6eaf195-7652-4319-bd15-476033e64896)
+
+### 🎭 Callback Map
+Every ActiveRecord callback (`before_save`, `after_create`, `before_validation`, etc.) is timed and grouped by model in the Request Detail view. Expensive callbacks surface immediately — including hidden side effects like callbacks that trigger additional queries.
+
+![Callback Map](https://github.com/user-attachments/assets/8a33c957-191a-4e23-83bf-99ec25b462a8)
+
+### 🛡️ Injected Panel
+A collapsible overlay injected into every HTML response showing the current request's score, query count, DB time, N+1 count, and callback time. Zero configuration. Disappears in production.
+
+![Injected Panel](https://github.com/user-attachments/assets/c95e590b-02e4-4b25-90bb-d3f013dae6ff)
+
+---
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "rails_vitals", group: :development
+```
+
+Run:
+
+```bash
+bundle install
+```
+
+Mount the engine in `config/routes.rb`:
+
+```ruby
+mount RailsVitals::Engine, at: "/rails_vitals"
+```
+
+That's it. Visit `/rails_vitals` and start browsing your app.
+
+---
+
+## Configuration
+
+RailsVitals works out of the box with sensible defaults. To customize, add an initializer:
+
+```ruby
+# config/initializers/rails_vitals.rb
+RailsVitals.configure do |config|
+  # Enable/disable instrumentation entirely
+  config.enabled = !Rails.env.production?
+
+  # Ring buffer size — how many requests to keep in memory
+  config.store_size = 200
+
+  # Query count thresholds for scoring
+  config.query_warn_threshold     = 10   # above this → score starts dropping
+  config.query_critical_threshold = 25   # above this → score = 0
+
+  # DB time thresholds (ms) for slow query detection
+  config.db_time_warn_ms     = 100
+  config.db_time_critical_ms = 500
+
+  # Admin UI authentication
+  # :none      → no auth (default for development)
+  # :basic     → HTTP Basic Auth
+  # lambda     → custom auth logic
+  config.auth = :none
+
+  # Basic auth credentials (if auth: :basic)
+  config.basic_auth_username = "admin"
+  config.basic_auth_password = "secret"
+
+  # Custom auth lambda (if auth: :lambda)
+  # config.auth = ->(request) { request.session[:admin] == true }
+end
+```
+
+---
+
+## Admin UI
+
+Navigate to `/rails_vitals` to access the full admin interface.
+
+| Page | Path | Description |
+|------|------|-------------|
+| Dashboard | `/rails_vitals` | Score distribution, health trend, query volume |
+| Requests | `/rails_vitals/requests` | Full request history with filters |
+| Request Detail | `/rails_vitals/requests/:id` | Queries, Query DNA, Callback Map, Score Projection |
+| Heatmap | `/rails_vitals/heatmap` | Endpoints ranked by worst health score |
+| Models | `/rails_vitals/models` | Per-model query breakdown |
+| N+1 Patterns | `/rails_vitals/n_plus_ones` | Cross-request N+1 aggregation with fix suggestions |
+| Association Map | `/rails_vitals/associations` | Live SVG model graph with N+1 and index annotations |
+
+---
+
+## How Scoring Works
+
+RailsVitals scores each request using a `CompositeScorer` with two weighted dimensions:
+
+```
+Score = (QueryScore × 40%) + (N+1Score × 60%)
+```
+
+**QueryScore** (40%) — penalizes query volume:
+- ≤ `query_warn_threshold` queries → 100
+- ≥ `query_critical_threshold` queries → 0
+- Between thresholds → linear interpolation
+
+**N+1Score** (60%) — penalizes detected patterns:
+- 0 patterns → 100
+- 1 pattern  → 75
+- 2 patterns → 50
+- 3 patterns → 25
+- 4+ patterns → 0
+
+N+1 patterns are weighted more heavily because they represent an architectural problem that grows worse as data scales not just a snapshot of current query volume.
+
+---
+
+## Query DNA Token Reference
+
+| Token | Color | Risk | What it means |
+|-------|-------|------|---------------|
+| `SELECT *` | Blue | ⚠ Warning | Fetches all columns — consider `.select(:id, :name)` |
+| `SELECT` | Blue | ✅ Healthy | Specific column selection |
+| `COUNT(*)` | Amber | ⚠ Warning | Aggregation in a loop = N+1 variant |
+| `AGGREGATE` | Amber | ⚠ Warning | SUM/AVG/MIN/MAX in a loop |
+| `FROM` | Green | ✅ Healthy | Identifies the model being queried |
+| `WHERE fk =` | Red | 🔴 Danger | Single FK lookup — the N+1 signature |
+| `WHERE` | Orange | — Neutral | Filter condition — check for missing index |
+| `IN (...)` | Green | ✅ Healthy | Batch lookup — eager loading is working |
+| `INNER JOIN` | Purple | — Neutral | `.joins()` — note: association not loaded |
+| `LEFT JOIN` | Purple | — Neutral | `.eager_load()` or `.left_joins()` |
+| `ORDER BY` | Cyan | ⚠ Warning | Ensure sort column has an index |
+| `LIMIT` | Gray | ✅ Healthy | Good — always paginate |
+| `OFFSET` | Red | ⚠ Warning | O(n) at scale — consider cursor pagination |
+| `GROUP BY` | Cyan | — Neutral | Consider counter cache for frequent use |
+
+---
+
+## N+1 Fix Suggestions
+
+RailsVitals generates fix suggestions by reflecting on your actual ActiveRecord associations, not by guessing. Given a detected pattern:
+
+```sql
+SELECT "likes".* FROM "likes" WHERE "likes"."post_id" = ?
+```
+
+It extracts the foreign key (`post_id`), infers the owner model (`Post`), reflects on `Post.reflect_on_all_associations`, and generates:
+
+```ruby
+Post.includes(:likes)
+```
+
+Real associations, real fix, zero guesswork.
+
+---
+
+## Association Map — Reading the Diagram
+
+- 🟢 **Green node** — model is queried, no N+1 detected
+- 🔴 **Red node** — N+1 patterns detected on this model's associations
+- ⬜ **Gray node** — model exists but hasn't been queried in recent requests
+- **Solid edge** — foreign key is indexed ✅
+- **Dashed edge** — foreign key is missing an index ⚠️
+- **Orange edge** — `has_many` / `has_one`
+- **Purple edge** — `belongs_to`
+- **Red edge** — association has active N+1 patterns
+
+Click any node to open the detail panel with query stats, association breakdown, fix suggestions, and links to affected requests.
+
+---
+
+## Architecture
+
+RailsVitals is a mountable Rails Engine with zero runtime dependencies beyond Rails itself.
+
+```
+rails_vitals/
+├── lib/
+│   └── rails_vitals/
+│       ├── engine.rb                          # Mountable engine
+│       ├── configuration.rb                   # Config object
+│       ├── collector.rb                       # Thread-local request collector
+│       ├── store.rb                           # Thread-safe in-memory ring buffer
+│       ├── request_record.rb                  # Immutable request snapshot
+│       ├── panel_renderer.rb                  # Injected HTML panel
+│       ├── sse_writer.rb                      # Server-Sent Events writer
+│       ├── notifications/
+│       │   └── subscriber.rb                  # AS::Notifications SQL + controller hooks
+│       ├── instrumentation/
+│       │   └── callback_instrumentation.rb    # Module prepend for AR callbacks
+│       ├── analyzers/
+│       │   ├── sql_tokenizer.rb               # Query DNA tokenizer
+│       │   ├── n_plus_one_aggregator.rb       # Cross-request N+1 aggregation
+│       │   └── association_mapper.rb          # AR reflection + SVG layout
+│       ├── scorers/
+│       │   ├── base_scorer.rb
+│       │   ├── query_scorer.rb                # 40% weight
+│       │   ├── n_plus_one_scorer.rb           # 60% weight
+│       │   └── composite_scorer.rb
+│       └── middleware/
+│           └── panel_injector.rb              # Rack middleware for panel injection
+└── app/
+    ├── controllers/rails_vitals/
+    │   ├── dashboard_controller.rb
+    │   ├── requests_controller.rb
+    │   ├── heatmap_controller.rb
+    │   ├── models_controller.rb
+    │   ├── n_plus_ones_controller.rb
+    │   ├── associations_controller.rb
+    │   └── live_controller.rb
+    └── views/rails_vitals/
+        ├── dashboard/
+        ├── requests/
+        ├── heatmap/
+        ├── models/
+        ├── n_plus_ones/
+        ├── associations/
+        └── live/
+```
+
+**Key architectural decisions:**
+
+- **Zero JS dependencies** — no Chartkick, no D3, no Chart.js. Tables for data, SVG for diagrams, vanilla JS for interactions.
+- **Thread-local Collector** — instrumentation state is stored per-thread, never shared between concurrent requests.
+- **In-memory ring buffer** — the Store keeps the last N requests in memory. No database writes, no schema migrations.
+- **Module prepend for callbacks** — callback instrumentation wraps `ActiveRecord::Base#run_callbacks` via `Module#prepend`. No TracePoint, no monkey-patching.
+- **ActiveSupport::Notifications** — SQL and controller events are captured via the standard Rails instrumentation bus.
+
+---
+
+## Philosophy
+
+Most Rails performance tools tell you what is slow. RailsVitals tells you **why it is slow** and **what the right mental model is**.
+
+Every feature is designed around a teaching moment:
+
+- Query DNA turns SQL into a readable fingerprint with explanations for each token
+- The Association Map connects your data model structure to live performance data
+- N+1 fix suggestions come from your actual associations, not generic advice
+- Score Projection lets you understand the impact of a fix before writing code
+- The Impact Simulator shows blast radius, how many requests are affected, how many queries would be saved
+
+The goal is not just a faster app. The goal is a developer who understands **why** the app was slow and **how** to prevent it next time.
+
+---
+
+## Requirements
+
+- Ruby 3.0+
+- Rails 7.0+
+- PostgreSQL (some internal query filters are PostgreSQL-specific)
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/your-username/rails_vitals
+cd rails_vitals
+bundle install
+```
+
+To test against a real app, add to your Gemfile with a local path:
+
+```ruby
+gem "rails_vitals", path: "../rails_vitals"
+```
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration.
+
+---
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](MIT-LICENSE).
+
+---
+
+## Author
+
+Built by [David](https://codeando.dev/)

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/rails_vitals/application.css

@@ -0,0 +1,180 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */
+
+ *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+body {
+  background: #0f0f1a;
+  color: #e2e8f0;
+  font-family: ui-monospace, monospace;
+  font-size: 13px;
+  min-height: 100vh;
+}
+
+a { color: #90cdf4; text-decoration: none; }
+a:hover { text-decoration: underline; }
+
+.nav {
+  background: #1a1a2e;
+  border-bottom: 1px solid #2d3748;
+  padding: 16px 24px;
+  display: flex;
+  align-items: center;
+  gap: 24px;
+}
+
+.nav-brand {
+  font-size: 20px;
+  font-weight: bold;
+  color: #90cdf4;
+  margin-right: 16px;
+}
+
+.nav a.nav-link {
+  color: #a0aec0;
+  font-size: 12px;
+}
+
+.nav a:hover { color: #e2e8f0; }
+.nav a.active { color: #90cdf4; }
+
+.container { padding: 24px; max-width: 1200px; margin: 0 auto; }
+
+.page-title {
+  font-size: 18px;
+  font-weight: bold;
+  color: #e2e8f0;
+  margin-bottom: 20px;
+}
+
+.card {
+  background: #1a1a2e;
+  border: 1px solid #2d3748;
+  border-radius: 8px;
+  padding: 16px;
+  margin-bottom: 16px;
+}
+
+.card-title {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: #a0aec0;
+  margin-bottom: 12px;
+
+  .card-title-description {
+    font-size: 10px;
+    color: #718096;
+    text-transform: none;
+    letter-spacing: normal;
+    margin-left: 8px;
+    font-weight: normal;
+  }
+}
+
+.badge {
+  display: inline-block;
+  padding: 2px 8px;
+  border-radius: 4px;
+  font-size: 11px;
+  font-weight: bold;
+}
+
+.badge-healthy    { background: #276749; color: #fff; }
+.badge-acceptable { background: #2b6cb0; color: #fff; }
+.badge-warning    { background: #b7791f; color: #fff; }
+.badge-critical   { background: #c53030; color: #fff; }
+
+table { width: 100%; border-collapse: collapse; }
+th {
+  text-align: left;
+  color: #a0aec0;
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  padding: 8px 12px;
+  border-bottom: 1px solid #2d3748;
+}
+td {
+  padding: 10px 12px;
+  border-bottom: 1px solid #1e2535;
+  color: #e2e8f0;
+}
+tr:hover td { background: #1e2535; }
+
+.grid-3 {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 16px;
+  margin-bottom: 16px;
+}
+
+.stat-card {
+  background: #1a1a2e;
+  border: 1px solid #2d3748;
+  border-radius: 8px;
+  padding: 16px;
+  text-align: center;
+}
+
+.stat-value {
+  font-size: 28px;
+  font-weight: bold;
+  color: #90cdf4;
+  margin-bottom: 4px;
+}
+
+.stat-label {
+  font-size: 11px;
+  color: #a0aec0;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+
+.filter-bar {
+  display: flex;
+  gap: 8px;
+  margin-bottom: 16px;
+  flex-wrap: wrap;
+}
+
+.filter-bar a {
+  padding: 4px 12px;
+  border: 1px solid #2d3748;
+  border-radius: 4px;
+  font-size: 11px;
+  color: #a0aec0;
+}
+
+.filter-bar a:hover,
+.filter-bar a.active { border-color: #90cdf4; color: #90cdf4; }
+
+.sql {
+  color: #90cdf4;
+  font-size: 11px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 400px;
+}
+
+.n1-badge {
+  background: #c53030;
+  color: #fff;
+  padding: 1px 6px;
+  border-radius: 3px;
+  font-size: 10px;
+}

data/app/controllers/rails_vitals/application_controller.rb

@@ -0,0 +1,30 @@
+module RailsVitals
+  class ApplicationController < ActionController::Base
+    before_action :authenticate!
+    before_action :flag_own_request
+
+    private
+
+    def authenticate!
+      auth = RailsVitals.config.auth
+
+      case auth
+      when :none
+        true
+      when :basic
+        authenticate_or_request_with_http_basic("RailsVitals") do |username, password|
+          username == RailsVitals.config.basic_auth_username &&
+            password == RailsVitals.config.basic_auth_password
+        end
+      when Proc
+        unless auth.call(self)
+          render plain: "Unauthorized", status: :unauthorized
+        end
+      end
+    end
+
+    def flag_own_request
+      Thread.current[:rails_vitals_own_request] = true
+    end
+  end
+end

data/app/controllers/rails_vitals/associations_controller.rb

@@ -0,0 +1,8 @@
+module RailsVitals
+  class AssociationsController < ApplicationController
+    def index
+      @nodes, @canvas_height = Analyzers::AssociationMapper.build(RailsVitals.store)
+      @node_map = @nodes.index_by(&:name)
+    end
+  end
+end

data/app/controllers/rails_vitals/dashboard_controller.rb

@@ -0,0 +1,59 @@
+module RailsVitals
+  class DashboardController < ApplicationController
+    def index
+      @records = RailsVitals.store.all.reverse
+      @total   = @records.size
+      @avg_score     = average(@records, :score)
+      @avg_queries   = average(@records, :total_query_count)
+      @avg_db_time   = average(@records, :total_db_time_ms)
+      @top_offenders = top_offenders(@records)
+      @health_trend       = health_trend_data(@records)
+      @score_distribution = score_distribution_data(@records)
+      @query_volume       = query_volume_data(@records)
+    end
+
+    private
+
+    def average(records, method)
+      return 0 if records.empty?
+
+      (records.sum(&method).to_f / records.size).round(1)
+    end
+
+    def top_offenders(records)
+      records
+        .group_by(&:endpoint)
+        .transform_values do |reqs|
+          {
+            count:          reqs.size,
+            avg_score:      average(reqs, :score),
+            avg_queries:    average(reqs, :total_query_count),
+            avg_db_time_ms: average(reqs, :total_db_time_ms)
+          }
+        end
+        .sort_by { |_, v| v[:avg_score] }
+        .first(5)
+    end
+
+    def health_trend_data(records)
+      records.first(10).map do |r|
+        [ r.endpoint, r.score ]
+      end
+    end
+
+    def score_distribution_data(records)
+      {
+        "Healthy (90-100)"   => records.count { |r| r.score >= 90 },
+        "Acceptable (70-89)" => records.count { |r| (70..89).include?(r.score) },
+        "Warning (50-69)"    => records.count { |r| (50..69).include?(r.score) },
+        "Critical (0-49)"    => records.count { |r| r.score < 50 }
+      }
+    end
+
+    def query_volume_data(records)
+      records.first(10).each_with_index.map do |r, i|
+        [ "##{i + 1} #{r.endpoint}", { queries: r.total_query_count, db_time: r.total_db_time_ms.round(1) } ]
+      end
+    end
+  end
+end

data/app/controllers/rails_vitals/heatmap_controller.rb

@@ -0,0 +1,39 @@
+module RailsVitals
+  class HeatmapController < ApplicationController
+    def index
+      records   = RailsVitals.store.all
+      @heatmap  = build_heatmap(records)
+      @total    = records.size
+    end
+
+    private
+
+    def build_heatmap(records)
+      records
+        .group_by(&:endpoint)
+        .map do |endpoint, reqs|
+          {
+            endpoint:         endpoint,
+            hits:             reqs.size,
+            avg_score:        average(reqs, :score),
+            avg_queries:      average(reqs, :total_query_count),
+            avg_db_time:      average(reqs, :total_db_time_ms),
+            avg_callback_time: average(reqs, :total_callback_time_ms),
+            n_plus_one_freq:  n_plus_one_frequency(reqs)
+          }
+        end
+        .sort_by { |row| row[:avg_score] }
+    end
+
+    def average(records, method)
+      return 0.0 if records.empty?
+      (records.sum { |r| r.public_send(method) }.to_f / records.size).round(1)
+    end
+
+    def n_plus_one_frequency(reqs)
+      reqs_with_n1 = reqs.count { |r| r.n_plus_one_patterns.any? }
+      return 0.0 if reqs.empty?
+      ((reqs_with_n1.to_f / reqs.size) * 100).round(1)
+    end
+  end
+end