⚡ 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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

Add to your Gemfile:

gem "rails_vitals", group: :development

Run:

bundle install

Mount the engine in config/routes.rb:

mount RailsVitals::Engine, at: "/rails_vitals"

That's it. Visit /rails_vitals and start browsing your app.

RailsVitals works out of the box with sensible defaults. To customize, add an initializer:

# 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

Navigate to /rails_vitals to access the full admin interface.

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.

RailsVitals generates fix suggestions by reflecting on your actual ActiveRecord associations, not by guessing. Given a detected pattern:

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:

Post.includes(:likes)

Real associations, real fix, zero guesswork.

• 🟢 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.

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.

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.

• Ruby 3.0+
• Rails 7.0+
• PostgreSQL (some internal query filters are PostgreSQL-specific)

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:

gem "rails_vitals", path: "../rails_vitals"

Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration.

The gem is available as open source under the terms of the MIT License.

Built by David