rails_pulse 0.3.0.pre.2 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6ec5ec95320f8d2158fd9e91a5ba062097e934eafa74a62338fcca24ebba443
-  data.tar.gz: f8f49ca49a92f92194583c3d02b07e6af5eb52e167e15684f99046eaa94643e9
+  metadata.gz: bc7710c1fd792d4caca32fe285af8c8d9c11f53cd5e31ba177e061d44f92600e
+  data.tar.gz: 483b8c6a00e0e24d2331895299dfdee8629bc44c39a5717697d1914317da39f4
 SHA512:
-  metadata.gz: 80b06492afb0eb55a87e422fc0bf2920b9c6dd8d8a025b3851f060b06e08792158250199a93ca6caca111c055f07033e981788473cc90e0733dc90d5c15e25b9
-  data.tar.gz: 7e97409c2903f3847b99ce5259354ebaf841c47975be411094b4440a74f89b0d51f64db9bae1fb9f5ca81649f65d4ac79230aee5f752946b9ac2da7ec1a1cf0b
+  metadata.gz: 79604b447464e692b6640be70cba507516481d1633e2ff556171c0e55a55fc6cc6d4077b1018bf567d2a72ec4b312fdcd05e575dfc6b5cc76635363b37655266
+  data.tar.gz: ffdc4668b94956f68697b9339aa1de8a2065f99e9346e8fa1e93e97d3e12adf0dc32cf4fc5b8ddc8a7bbe24d44392ec6d03f69060f6574d5bb05e2eda6285915

data/README.md

@@ -1,133 +1,49 @@
 <div align="center">
   <img src="app/assets/images/rails_pulse/rails-pulse-logo.png" alt="Rails Pulse" width="200" />
-
-  # Rails Pulse
-
-  **Real-time performance monitoring and debugging for Rails applications**
-
-  ![Gem Version](https://img.shields.io/gem/v/rails_pulse)
-  ![Rails Version](https://img.shields.io/badge/Rails-7.2+-8.1-blue)
-  ![License](https://img.shields.io/badge/License-MIT-green)
-  ![Ruby Version](https://img.shields.io/badge/Ruby-3.0+-red)
 </div>
 
 ---
 
-## Table of Contents
-
-- [Introduction](#introduction)
-- [Features](#features)
-- [Screenshots](#screenshots)
-- [Getting Started](#getting-started)
-  - [Installation](#installation)
-  - [Quick Setup](#quick-setup)
-  - [Basic Configuration](#basic-configuration)
-- [Background Job Monitoring](#background-job-monitoring)
-  - [Overview](#overview)
-  - [Supported Adapters](#supported-adapters)
-  - [Job Tracking Configuration](#job-tracking-configuration)
-  - [Privacy & Security](#privacy--security)
-- [Authentication](#authentication)
-  - [Authentication Setup](#authentication-setup)
-  - [Authentication Examples](#authentication-examples)
-- [Tagging System](#tagging-system)
-  - [Configuring Tags](#configuring-tags)
-  - [Using Tags](#using-tags)
-  - [Filtering by Tags](#filtering-by-tags)
-- [Data Management](#data-management)
-  - [Cleanup Strategies](#cleanup-strategies)
-  - [Cleanup Configuration](#cleanup-configuration)
-  - [Manual Cleanup Operations](#manual-cleanup-operations)
-- [Separate Database Support](#separate-database-support)
-  - [Configuration](#configuration)
-  - [Database Configuration](#database-configuration)
-  - [Schema Loading](#schema-loading)
-- [Performance Impact](#performance-impact)
-- [Standalone Dashboard Deployment](#standalone-dashboard-deployment)
-- [Testing](#testing)
-- [Technology Stack](#technology-stack)
-- [Advantages Over Other Solutions](#advantages-over-other-solutions)
-- [License](#license)
+# Rails Pulse
 
----
+**Self-hosted performance monitoring for Rails apps**
 
-## Introduction
+![Gem Version](https://img.shields.io/gem/v/rails_pulse)
+![Rails Version](https://img.shields.io/badge/Rails-7.2%2B-blue)
+![License](https://img.shields.io/badge/License-MIT-green)
+![Ruby Version](https://img.shields.io/badge/Ruby-3.0%2B-red)
 
-Rails Pulse is a comprehensive performance monitoring and debugging gem that provides insights into your Rails application's health. Built as a Rails Engine, it seamlessly integrates with your existing application to capture, analyze, and visualize performance metrics without impacting your production workload.
+Rails Pulse is a Rails engine that monitors your app's performance from the inside. It tracks slow requests, N+1 queries, SQL performance, and background jobs. All data stays in your own database, no third-party cloud, no SaaS subscription, no data leaving your servers.
 
-## Features
-
-### Performance Monitoring
-- Interactive dashboard with response time charts and request analytics
-- SQL query performance tracking with slow query identification
-- Route-specific metrics with configurable performance thresholds
-- **Background job monitoring** with execution tracking and failure analysis
-- Week-over-week trend analysis with visual indicators
-
-### Background Job Tracking
-- **Universal job tracking** compatible with all ActiveJob adapters
-- Monitor job performance, failures, and retries
-- Track individual job executions with detailed metrics
-- View operations and SQL queries executed during jobs
-- Configurable privacy controls for job arguments
-
-### Developer Experience
-- Zero configuration setup with sensible defaults
-- Beautiful responsive interface with dark/light mode
-- Smart caching with minimal performance overhead
-- Multiple database support (SQLite, PostgreSQL, MySQL)
-
-### Organization & Filtering
-- Flexible tagging system for routes, requests, queries, and jobs
-- Filter performance data by custom tags
-- Organize monitoring data by environment, priority, or custom categories
-
-## Screenshots
-
-<table>
+<table border="0">
+  <tr border="0" style="border:0">
+    <td border="0" style="border:0">
+    <img src="app/assets/images/rails_pulse/dashboard.png" alt="Dashboard" width="400" /></td>
+    <td style="border:0"><img src="app/assets/images/rails_pulse/request-show.png" alt="Request detail" width="400" /></td>
+  </tr>
   <tr>
-    <td><img src="app/assets/images/rails_pulse/dashboard.png" alt="Rails Pulse Dashboard" width="400" /></td>
-    <td><img src="app/assets/images/rails_pulse/request.png" alt="Rails Pulse Requests" width="400" /></td>
+    <td style="border:0"><img src="app/assets/images/rails_pulse/query-show.png" alt="Query detail" width="400" /></td>
+    <td style="border:0"><img src="app/assets/images/rails_pulse/route-show.png" alt="Route detail" width="400" /></td>
   </tr>
 </table>
 
+## Installation
 
-## Getting Started
-
-### Installation
-
-Add Rails Pulse to your application's Gemfile:
+Add to your Gemfile:
 
 ```ruby
 gem 'rails_pulse'
 ```
 
-Install the gem:
+Run the installer:
 
 ```bash
 bundle install
-```
-
-Generate the installation files:
-
-```bash
-# Install with single database setup (default - recommended)
 rails generate rails_pulse:install
-
-# Or install with separate database setup
-rails generate rails_pulse:install --database=separate
-```
-
-**For single database setup (default):**
-```bash
-rails db:migrate    # Creates Rails Pulse tables in your main database
+rails db:migrate
 ```
 
-**For separate database setup:**
-1. Configure `config/database.yml` with your Rails Pulse database settings
-2. Run: `rails db:prepare` to create and load the schema
-
-Add the Rails Pulse route to your application:
+Mount the dashboard in `config/routes.rb`:
 
 ```ruby
 Rails.application.routes.draw do
@@ -135,757 +51,74 @@ Rails.application.routes.draw do
 end
 ```
 
-Schedule background jobs:
+Schedule the background jobs:
 
 ```ruby
-# Schedule to run 5 minutes past every hour. cron: 5 * * * *
-RailsPulse::SummaryJob.perform_later
-
-# Schedule to run daily. cron: 0 1 * * *
-RailsPulse::CleanupJob.perform_later
+RailsPulse::SummaryJob.perform_later  # cron: 5 * * * *
+RailsPulse::CleanupJob.perform_later  # cron: 0 1 * * *
 ```
 
-### Quick Setup
+Your dashboard is now at `http://localhost:3000/rails_pulse`.
 
-Rails Pulse automatically starts collecting performance data once installed. Access your monitoring dashboard at:
+Full install guide: [railspulse.com/documentation/installation](https://railspulse.com/documentation/installation)
 
-```
-http://localhost:3000/rails_pulse
-```
-
-**Database Setup:**
-- **Single Database (default)**: Rails Pulse tables are created in your main database - no additional configuration needed
-- **Separate Database**: See the [Separate Database Support](#separate-database-support) section for setup instructions
+Separate database setup: [railspulse.com/documentation/database](https://railspulse.com/documentation/database)
 
-### Basic Configuration
+## Configuration
 
-Customize Rails Pulse in `config/initializers/rails_pulse.rb`:
+Rails Pulse works out of the box with sensible defaults. To customise, edit `config/initializers/rails_pulse.rb`:
 
 ```ruby
 RailsPulse.configure do |config|
-  # Enable or disable Rails Pulse
   config.enabled = true
 
-  # Set performance thresholds for route response times (in milliseconds)
-  config.route_thresholds = {
-    slow: 500,
-    very_slow: 1500,
-    critical: 3000
-  }
-
-  # Set performance thresholds for request response times (in milliseconds)
   config.request_thresholds = {
     slow: 700,
     very_slow: 2000,
     critical: 4000
   }
 
-  # Set performance thresholds for database queries (in milliseconds)
-  config.query_thresholds = {
-    slow: 100,
-    very_slow: 500,
-    critical: 1000
-  }
-
-  # Set performance thresholds for background jobs (in milliseconds)
-  config.job_thresholds = {
-    slow: 5_000,      # 5 seconds
-    very_slow: 30_000, # 30 seconds
-    critical: 60_000   # 1 minute
-  }
-
-  # Asset tracking configuration
-  config.track_assets = false       # Ignore asset requests by default
-  config.custom_asset_patterns = [] # Additional asset patterns to ignore
-
-  # Job tracking configuration
-  config.track_jobs = true          # Enable background job tracking
-  config.capture_job_arguments = false # Disable argument capture for privacy
-
-  # Rails Pulse mount path (optional)
-  # Specify if Rails Pulse is mounted at a custom path to prevent self-tracking
-  config.mount_path = nil  # e.g., "/admin/monitoring"
-
-  # Route filtering - ignore specific routes from performance tracking
-  config.ignored_routes = []    # Array of strings or regex patterns
-  config.ignored_requests = []  # Array of request patterns to ignore
-  config.ignored_queries = []   # Array of query patterns to ignore
-  config.ignored_jobs = []      # Array of job class names to ignore
-  config.ignored_queues = []    # Array of queue names to ignore
-
-  # Tagging system - define available tags for categorizing performance data
-  config.tags = ["production", "staging", "critical", "needs-optimization"]
-
-  # Data cleanup
-  config.archiving_enabled = true         # Enable automatic cleanup
-  config.full_retention_period = 30.days  # Delete records older than this
-  config.max_table_records = {            # Maximum records per table
-    rails_pulse_operations: 100_000,
-    rails_pulse_requests: 50_000,
-    rails_pulse_job_runs: 50_000,
-    rails_pulse_queries: 10_000,
-    rails_pulse_routes: 1_000,
-    rails_pulse_jobs: 1_000
-  }
-
-  # Multiple database support (optional)
-  # Uncomment to store Rails Pulse data in a separate database
-  # config.connects_to = {
-  #   database: { writing: :rails_pulse, reading: :rails_pulse }
-  # }
-end
-```
-
-## Background Job Monitoring
-
-Rails Pulse provides comprehensive monitoring for ActiveJob background jobs, tracking performance, failures, and execution details across all major job adapters.
-
-### Overview
-
-Background job monitoring is **enabled by default** and works automatically with any ActiveJob adapter. Rails Pulse captures:
-
-- **Job execution metrics**: Duration, status, retry attempts
-- **Failure tracking**: Error class, error message, failure rates
-- **Performance analysis**: Slow jobs, aggregate metrics by job class
-- **Operation timeline**: SQL queries and operations during job execution
-- **Job arguments**: Optional capture for debugging (disabled by default for privacy)
-
-Access the jobs dashboard at `/rails_pulse/jobs` to view:
-- All job classes with aggregate metrics (total runs, failure rate, average duration)
-- Individual job executions with detailed performance data
-- Filtering by time range, status, queue, and performance thresholds
-- Tagging support for organizing jobs by team, priority, or category
-
-### Supported Adapters
-
-Rails Pulse works with all ActiveJob adapters through universal tracking:
-
-- **Sidekiq** - Enhanced tracking via custom middleware
-- **Solid Queue** - Universal ActiveJob tracking
-- **Good Job** - Universal ActiveJob tracking
-- **Delayed Job** - Enhanced tracking via custom plugin
-- **Resque** - Universal ActiveJob tracking
-- **Any ActiveJob adapter** - Falls back to universal tracking
-
-No additional configuration needed - job tracking works out of the box with your existing setup.
-
-### Job Tracking Configuration
-
-Customize job tracking in your Rails Pulse initializer:
-
-```ruby
-RailsPulse.configure do |config|
-  # Enable or disable job tracking (default: true)
   config.track_jobs = true
+  config.capture_job_arguments = false  # keep false to protect sensitive data
 
-  # Set performance thresholds for jobs (in milliseconds)
-  config.job_thresholds = {
-    slow: 5_000,        # 5 seconds
-    very_slow: 30_000,  # 30 seconds
-    critical: 60_000    # 1 minute
-  }
-
-  # Ignore specific job classes from tracking
-  config.ignored_jobs = [
-    "ActiveStorage::AnalyzeJob",
-    "ActiveStorage::PurgeJob"
-  ]
-
-  # Ignore specific queues from tracking
-  config.ignored_queues = ["low_priority", "mailers"]
-
-  # Capture job arguments for debugging (default: false)
-  # WARNING: May expose sensitive data - use with caution
-  config.capture_job_arguments = false
-
-  # Configure adapter-specific settings
-  config.job_adapters = {
-    sidekiq: { enabled: true, track_queue_depth: false },
-    solid_queue: { enabled: true, track_recurring: false },
-    good_job: { enabled: true, track_cron: false },
-    delayed_job: { enabled: true },
-    resque: { enabled: true }
-  }
-end
-```
-
-**Disabling job tracking for specific jobs:**
-
-```ruby
-class MyBackgroundJob < ApplicationJob
-  # Skip Rails Pulse tracking for this job
-  def perform(*args)
-    RailsPulse.with_tracking_disabled do
-      # Job logic here
-    end
-  end
-end
-```
-
-### Privacy & Security
-
-**Job argument capture is disabled by default** to protect sensitive information. Job arguments may contain:
-- User credentials or tokens
-- Personal identifiable information (PII)
-- API keys or secrets
-- Sensitive business data
-
-Only enable `capture_job_arguments` in development or when explicitly needed for debugging. Consider using parameter filtering if you need to capture arguments:
-
-```ruby
-# In your job class
-class SensitiveJob < ApplicationJob
-  def perform(user_id:, api_key:)
-    # Rails Pulse will track execution but not arguments by default
-  end
+  config.full_retention_period = 30.days
 end
 ```
 
-**Performance impact:**
-- Minimal overhead: ~1-2ms per job execution
-- No blocking of job processing
-- Configurable cleanup prevents database growth
-- Can be disabled per-job or globally
+Full configuration reference: [railspulse.com/documentation/advanced](https://railspulse.com/documentation/advanced)
 
 ## Authentication
 
-Rails Pulse supports flexible authentication to secure access to your monitoring dashboard.
-
-### Authentication Setup
-
-Enable authentication by configuring the following options in your Rails Pulse initializer:
+Rails Pulse has no built-in authentication, you protect the dashboard using your app's existing auth. Add an `authentication_method` to the initializer:
 
 ```ruby
-# config/initializers/rails_pulse.rb
 RailsPulse.configure do |config|
-  # Enable authentication
   config.authentication_enabled = true
-
-  # Where to redirect unauthorized users (optional, defaults to "/")
   config.authentication_redirect_path = "/login"
 
-  # Define your authentication logic
   config.authentication_method = proc {
-    # Your authentication logic here
-  }
-end
-```
-
-### Authentication Examples
-
-Rails Pulse works with any authentication system. Here are common patterns:
-
-#### Devise with Admin Role
-
-```ruby
-config.authentication_method = proc {
-  unless user_signed_in? && current_user.admin?
-    redirect_to main_app.root_path, alert: "Access denied"
-  end
-}
-```
-
-#### Custom Authorization Logic
-
-```ruby
-config.authentication_method = proc {
-  current_user = User.find_by(id: session[:user_id])
-  unless current_user&.can_access_monitoring?
-    render plain: "Forbidden", status: :forbidden
-  end
-}
-```
-
-## Tagging System
-
-Rails Pulse includes a flexible tagging system that allows you to categorize and organize your performance data. Tag routes, requests, queries, jobs, and job runs with custom labels to better organize and filter your monitoring data.
-
-### Configuring Tags
-
-Define available tags in your Rails Pulse initializer:
-
-```ruby
-RailsPulse.configure do |config|
-  config.tags = [
-    "production",
-    "staging",
-    "critical",
-    "needs-optimization",
-    "high-traffic",
-    "background-job"
-  ]
-end
-```
-
-### Using Tags
-
-**Tag from the UI:**
-
-1. Navigate to any route, request, query, job, or job run detail page
-2. Click the "+ tag" button next to the record
-3. Select from your configured tags
-4. Remove tags by clicking the × button on any tag badge
-
-**Tag Programmatically:**
-
-```ruby
-# Tag a route
-route = RailsPulse::Route.find_by(path: "/api/users")
-route.add_tag("critical")
-route.add_tag("high-traffic")
-
-# Tag a query
-query = RailsPulse::Query.find_by(normalized_sql: "SELECT * FROM users WHERE id = ?")
-query.add_tag("needs-optimization")
-
-# Tag a job
-job = RailsPulse::Job.find_by(name: "UserNotificationJob")
-job.add_tag("high-priority")
-job.add_tag("user-facing")
-
-# Tag a specific job run
-job_run = RailsPulse::JobRun.find_by(run_id: "abc123")
-job_run.add_tag("investigated")
-
-# Remove a tag
-route.remove_tag("critical")
-
-# Check if has tag
-route.has_tag?("production") # => true
-```
-
-### Filtering by Tags
-
-Use the global filters modal to filter performance data by tags:
-
-1. Click the filter icon in the top navigation
-2. Select one or more tags from the tag selector
-3. Apply filters to see only records with those tags
-4. Tags appear as badges in all data tables for quick visual identification
-
-**Common Tagging Strategies:**
-
-- **By Environment**: `production`, `staging`, `development`
-- **By Priority**: `critical`, `high`, `medium`, `low`
-- **By Status**: `needs-optimization`, `investigating`, `resolved`
-- **By Type**: `api`, `background-job`, `user-facing`, `admin`
-- **By Team**: `team-frontend`, `team-backend`, `team-data`
-
-## Data Management
-
-Rails Pulse provides data cleanup to prevent your monitoring database from growing indefinitely while preserving essential performance insights.
-
-### Cleanup Strategies
-
-**Time-based Cleanup**
-- Automatically delete performance records older than a specified period
-- Configurable retention period (default: 2 days)
-- Keeps recent data for debugging while removing historical noise
-
-**Count-based Cleanup**
-- Enforce maximum record limits per table
-- Prevents any single table from consuming excessive storage
-- Configurable limits for each Rails Pulse table
-
-### Cleanup Configuration
-
-```ruby
-RailsPulse.configure do |config|
-  # Enable or disable automatic cleanup
-  config.archiving_enabled = true
-
-  # Time-based retention
-  config.full_retention_period = 2.weeks
-
-  # Count-based retention - maximum records per table
-  config.max_table_records = {
-    rails_pulse_requests: 10000,    # HTTP requests
-    rails_pulse_operations: 50000,  # Operations within requests
-    rails_pulse_routes: 1000,       # Unique routes
-    rails_pulse_queries: 500        # Normalized SQL queries
-  }
-end
-```
-
-### Manual Cleanup Operations
-
-**Run cleanup manually:**
-```bash
-rails rails_pulse:cleanup
-```
-
-**Check current database status:**
-```bash
-rails rails_pulse:cleanup_stats
-```
-
-**Schedule automated cleanup:**
-```ruby
-RailsPulse::CleanupJob.perform_later
-```
-
-## Separate Database Support
-
-Rails Pulse offers two database setup options to fit your application's needs:
-
-### Option 1: Single Database (Default - Recommended)
-
-Stores Rails Pulse data in your main application database alongside your existing tables. This is the simplest setup and works great for most applications.
-
-**Advantages:**
-- Zero additional configuration required
-- Simpler backup and deployment strategies
-- Works with any database (SQLite, PostgreSQL, MySQL)
-
-**Installation:**
-```bash
-rails generate rails_pulse:install
-rails db:migrate
-```
-
-### Option 2: Separate Database
-
-Stores Rails Pulse data in a dedicated database, completely isolated from your main application.
-
-**Use a separate database when you want:**
-- **Isolating monitoring data** from your main application database
-- **Using different database engines** optimized for time-series data
-- **Scaling monitoring independently** from your application
-- **Simplified backup strategies** with separate retention policies
-
-### Configuration
-
-To use a separate database, install with the `--database=separate` flag, then configure the `connects_to` option in your Rails Pulse initializer:
-
-```ruby
-RailsPulse.configure do |config|
-  # Single separate database
-  config.connects_to = {
-    database: { writing: :rails_pulse, reading: :rails_pulse }
-  }
-
-  # Or primary/replica configuration
-  config.connects_to = {
-    database: { writing: :rails_pulse_primary, reading: :rails_pulse_replica }
+    unless user_signed_in? && current_user.admin?
+      redirect_to main_app.root_path, alert: "Access denied"
+    end
   }
 end
 ```
 
-### Database Configuration
-
-Add the corresponding database configurations to your `config/database.yml`:
-
-```yaml
-# For SQLite
-production:
-  # ... your main database ...
-  rails_pulse:
-    adapter: sqlite3
-    database: storage/rails_pulse_production.sqlite3
-    migrations_paths: db/rails_pulse_migrate
-    pool: 5
-    timeout: 5000
-
-# For PostgreSQL
-production:
-  # ... your main database ...
-  rails_pulse:
-    adapter: postgresql
-    database: myapp_rails_pulse_production
-    username: rails_pulse_user
-    password: <%= Rails.application.credentials.dig(:rails_pulse, :database_password) %>
-    host: localhost
-    migrations_paths: db/rails_pulse_migrate
-    pool: 5
-
-# For MySQL
-production:
-  # ... your main database ...
-  rails_pulse:
-    adapter: mysql2
-    database: myapp_rails_pulse_production
-    username: rails_pulse_user
-    password: <%= Rails.application.credentials.dig(:rails_pulse, :database_password) %>
-    host: localhost
-    migrations_paths: db/rails_pulse_migrate
-    pool: 5
-```
-
-### Installation Steps
-
-**For separate database setup:**
-
-1. **Generate installation files:**
-   ```bash
-   rails generate rails_pulse:install --database=separate
-   ```
-
-2. **Configure `config/database.yml`** (see examples above)
-
-3. **Create and load the schema:**
-   ```bash
-   rails db:prepare
-   ```
-   This automatically creates the database and loads the Rails Pulse schema.
-
-**Schema Management:**
-
-The schema file `db/rails_pulse_schema.rb` serves as your single source of truth for the database structure. It:
-- Defines all Rails Pulse tables in one place
-- Is loaded by the installation migration
-- Should not be deleted or modified
-- Future updates will provide migrations in `db/rails_pulse_migrate/`
-
-## Performance Impact
-
-Rails Pulse uses **fiber-based async tracking** for minimal performance overhead:
+Authentication guide: [railspulse.com/documentation/authentication](https://railspulse.com/documentation/authentication)
 
-- **Request overhead:** ~0.1ms per request (data collection only)
-- **Database writes:** Non-blocking, handled in background fibers
-- **Memory allocation:** Minimal, ~200 KB per request (temporary)
-- **Thread safety:** Proper connection pooling with isolated database connections
-
-This is handled automatically and requires no configuration.
-
-## Standalone Dashboard Deployment
-
-For production environments, you can run the Rails Pulse dashboard as a standalone application, separate from your main Rails app. This provides several benefits:
-
-- **Dashboard remains accessible when main app is under heavy load**
-- **Separate resource allocation** for monitoring vs application
-- **Enhanced security** - isolate dashboard access from public app
-- **Independent scaling** - dashboard doesn't scale with app instances
-
-**Quick Setup:**
-
-```bash
-# Option 1: Set DATABASE_URL environment variable (recommended for production)
-export DATABASE_URL="postgresql://user:pass@host/db"
-bundle exec rails_pulse_server
-
-# Option 2: Use config/database.yml (recommended for development)
-# Looks for 'rails_pulse' connection, falls back to primary
-# No environment variable needed - automatically reads from config/database.yml
-bundle exec rails_pulse_server
-```
-
-**Healthcheck Endpoint:**
-
-The standalone server includes a `/health` endpoint that verifies database connectivity:
-
-```bash
-curl http://localhost:3001/health
-# Returns: {"status":"ok","mode":"dashboard","database":"connected","timestamp":"..."}
-```
-
-**Deployment Options:**
-
-1. **Separate subdomain (recommended):**
-   ```nginx
-   server {
-       server_name pulse.myapp.com;
-       location / {
-           proxy_pass http://localhost:3001;
-           proxy_set_header Host $host;
-           proxy_set_header X-Real-IP $remote_addr;
-           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-           proxy_set_header X-Forwarded-Proto $scheme;
-       }
-   }
-   ```
-
-2. **Kamal Deployment:**
-   Deploy the dashboard as an accessory
-
-   ```yaml
-   # config/deploy.yml
-   accessories:
-     rails_pulse:
-       image: your-app-image  # Same image as your main app
-       host: your-server
-       cmd: bundle exec rails_pulse_server
-       env:
-         clear:
-           DATABASE_URL: "postgresql://user:pass@host/db"
-           RAILS_ENV: production
-           SECRET_KEY_BASE: <%= ENV.fetch("SECRET_KEY_BASE") %>
-       port: "3001:3001"
-       healthcheck:
-         path: /health
-         port: 3001
-         interval: 10s
-         timeout: 5s
-   ```
-
-**Note:** When running standalone, the dashboard is read-only and doesn't track its own requests (tracking is automatically disabled).
-
-For detailed deployment instructions, see [docs/deployment-modes.md](docs/deployment-modes.md).
-
-## Testing
-
-Rails Pulse includes a comprehensive test suite designed for speed and reliability across multiple databases and Rails versions.
-
-### Running the Complete Test Suite
-
-```bash
-# Run all tests (unit, functional, integration, instrumentation)
-rails test:all
-```
-
-### Running Individual Test Types
-
-```bash
-# Unit tests (models, helpers, utilities)
-rails test:unit
-
-# Functional tests (controllers, views)
-rails test:functional
-
-# Integration tests (end-to-end workflows)
-rails test:integration
-```
-
-### Running Individual Test Files
-
-```bash
-# Run a specific test file
-rails test test/models/rails_pulse/request_test.rb
-```
-
-### Multi-Database and Rails Version Testing
-
-Test against multiple databases and Rails versions using the matrix task:
-
-```bash
-# Test all database and Rails version combinations locally
-rails test:matrix
-```
-
-This command tests all combinations locally:
-- **Databases**: SQLite3, PostgreSQL, MySQL2 (local testing only)
-- **Rails versions**: 7.2, 8.0, 8.1
-
-**Note**: CI only tests SQLite3 + PostgreSQL for reliability. MySQL is available for local testing but excluded from CI due to flakiness.
-
-### Development Environment Setup
-
-1. **Copy the environment template:**
-   ```bash
-   cp .env.example .env
-   ```
-
-2. **Configure your database credentials in `.env` (for local multi-database testing):**
-   ```bash
-   # PostgreSQL Configuration (used in CI + local)
-   POSTGRES_USERNAME=your_username
-   POSTGRES_PASSWORD=your_password
-   POSTGRES_HOST=localhost
-   POSTGRES_PORT=5432
-
-   # MySQL Configuration (local testing only)
-   MYSQL_USERNAME=root
-   MYSQL_PASSWORD=your_password
-   MYSQL_HOST=localhost
-   MYSQL_PORT=3306
-   ```
-
-3. **Create test databases:**
-   ```bash
-   # PostgreSQL
-   createdb rails_pulse_test
-
-   # MySQL
-   mysql -u root -p -e "CREATE DATABASE rails_pulse_test;"
-   ```
-
-### Manual Database Testing
-
-Test individual databases locally:
-
-```bash
-# Test with SQLite (default)
-rails test:all
+## Features
 
-# Test with PostgreSQL
-DB=postgresql FORCE_DB_CONFIG=true rails test:all
+- **Request monitoring** — every request is timed and stored with its route, status, SQL count, and duration. Slow requests are flagged automatically based on thresholds you control.
+- **Query analysis** — captures the queries behind each request, detects N+1 patterns, and tracks normalized SQL across requests so you can see which queries are hurting you in production, not just in development.
+- **Job tracking** — monitors background job duration, queue wait time, and failure rates. Works with any Active Job adapter.
+- **System health bar** — at-a-glance dashboard summary showing healthy, slow, and critical counts across your routes, queries, jobs, and storage. Lets you see the overall state of your app before drilling into specifics.
+- **No data leaves your app** — everything is stored in your own database. No third-party cloud, no SaaS subscription, no outbound connections.
+- **Low overhead** — tracking is async and uses a thread-local flag to skip recording Rails Pulse's own internal requests.
 
-# Test with MySQL (local only)
-DB=mysql2 FORCE_DB_CONFIG=true rails test:all
-```
+## Contributing
 
-### CI Testing
-
-GitHub Actions CI automatically tests:
-- **Databases**: SQLite3, PostgreSQL only (MySQL excluded for reliability)
-- **Rails versions**: 7.2, 8.0, 8.1
-- **Environment**: Uses memory SQLite and PostgreSQL service
-
-**Local vs CI differences**:
-- **Local**: Can test all 3 databases (SQLite3, PostgreSQL, MySQL2)
-- **CI**: Only SQLite3 + PostgreSQL for fast, reliable builds
-- **Database switching**: Requires `FORCE_DB_CONFIG=true` locally
-
-## Technology Stack
-
-Rails Pulse is built using modern, battle-tested technologies that ensure reliability, performance, and maintainability:
-
-### **Frontend Technologies**
-- **[CSS Zero](https://github.com/lazaronixon/css-zero)** - Modern utility-first CSS framework bundled for asset independence
-- **[Stimulus](https://stimulus.hotwired.dev/)** - Progressive JavaScript framework for enhanced interactivity
-- **Fetch API + DOMParser** - Lightweight partial page updates with CSP-safe DOM manipulation
-
-### **Data Visualization**
-- **[Apache ECharts](https://echarts.apache.org/)** - Powerful, interactive charting library
-- **[Lucide Icons](https://lucide.dev/)** - Beautiful, consistent iconography with pre-compiled SVG bundle
-
-### **Asset Management**
-- **Pre-compiled Assets** - All CSS, JavaScript, and icons bundled into the gem
-- **CSP-Safe Implementation** - Secure DOM methods and nonce-based asset loading
-- **Build System** - Node.js-based build process for asset compilation
-- **Zero External Dependencies** - Self-contained assets work with any Rails build system
-
-### **Performance & Optimization**
-- **[Request Store](https://github.com/steveklabnik/request_store)** - Thread-safe request-scoped storage for performance data
-- **[Rails Caching](https://guides.rubyonrails.org/caching_with_rails.html)** - Fragment caching with smart invalidation strategies
-- **[ActiveRecord Instrumentation](https://guides.rubyonrails.org/active_support_instrumentation.html)** - Built-in Rails performance monitoring hooks
-
-### **Development & Testing**
-- **[Rails Generators](https://guides.rubyonrails.org/generators.html)** - Automated installation and configuration
-- **[Omakase Ruby Styling](https://github.com/rails/rubocop-rails-omakase)** - Consistent code formatting and style
-
-## Advantages Over Other Solutions
-
-### **vs. Application Performance Monitoring (APM) Services**
-- **No External Dependencies**: Everything runs in your Rails application with pre-compiled assets
-- **Zero Monthly Costs**: No subscription fees or usage-based pricing
-- **Data Privacy**: All performance data stays in your database(s)
-- **Customizable**: Full control over metrics, thresholds, and interface
-- **Asset Independence**: Works with any Rails build system (Sprockets, esbuild, Webpack, Vite)
-
-### **vs. Custom Monitoring Solutions**
-- **Batteries Included**: Complete monitoring solution out of the box
-- **Proven Architecture**: Built on Rails best practices
-- **Community Driven**: Open source with active development
-- **Professional Design**: Production-ready interface
-
-### **Key Differentiators**
-- **Rails-Native**: Designed specifically for Rails applications
-- **Developer Experience**: Optimized for debugging and development
-- **Positive Focus**: Celebrates good performance alongside problem identification
-- **Contextual Insights**: Deep Rails framework integration for meaningful metrics
-- **Security First**: CSP-compliant by default with secure asset handling
-- **Zero Build Dependencies**: Pre-compiled assets work with any Rails setup
-- **Flexible Data Storage**: Support for multiple database backends (SQLite, PostgreSQL, MySQL)
+Bug reports and pull requests are welcome on [GitHub](https://github.com/railspulse/rails_pulse).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
----
-
-<div align="center">
-  <strong>Built with ❤️ for the Rails community</strong>
-
-  [Issues](https://github.com/railspulse/rails_pulse/issues) •
-  [Discussions](https://github.com/railspulse/rails_pulse/discussions)
-</div>
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -186,7 +186,7 @@ end
 
 desc "Test all database and Rails version combinations"
 task :test_matrix do
-  databases = %w[sqlite3 postgresql mysql2]
+  databases = %w[mysql2 postgresql sqlite3]
   rails_versions = %w[rails-7-2 rails-8-0 rails-8-1]
 
   failed_combinations = []

data/app/controllers/rails_pulse/requests_controller.rb

@@ -125,7 +125,7 @@ module RailsPulse
     end
 
     def set_request
-      @request = Request.find(params[:id])
+      @request = Request.includes(operations: :query).find(params[:id])
     end
   end
 end

data/db/rails_pulse_migrate/{20260420000001_expand_normalized_sql_column.rb → 20260420000001_expand_normalized_query_column.rb}

@@ -1,4 +1,4 @@
-class ExpandNormalizedSqlColumn < ActiveRecord::Migration[7.0]
+class ExpandNormalizedQueryColumn < ActiveRecord::Migration[7.0]
   def up
     return unless table_exists?(:rails_pulse_queries)
 

data/lib/generators/rails_pulse/templates/db/rails_pulse_schema.rb

@@ -40,8 +40,8 @@ RailsPulse::Schema ||= lambda do |connection|
 
   unless connection.table_exists?(:rails_pulse_queries)
     connection.create_table :rails_pulse_queries do |t|
-      t.string :hashed_sql, limit: 32, null: false, comment: "MD5 hash of normalized SQL for indexing"
-      t.text :normalized_sql, null: false, comment: "Normalized SQL query string (e.g., SELECT * FROM users WHERE id = ?)"
+      t.string :hashed_sql, limit: 32, null: false, comment: "MD5 hash of normalized SQL for fast lookups and uniqueness"
+      t.text :normalized_sql, null: false, comment: "Full normalized SQL query string (e.g., SELECT * FROM users WHERE id = ?)"
       t.datetime :analyzed_at, comment: "When query analysis was last performed"
       t.text :explain_plan, comment: "EXPLAIN output from actual SQL execution"
       t.text :issues, comment: "JSON array of detected performance issues"
@@ -68,6 +68,7 @@ RailsPulse::Schema ||= lambda do |connection|
       t.string :controller_action, comment: "Controller and action handling the request (e.g., PostsController#show)"
       t.timestamp :occurred_at, null: false, comment: "When the request started"
       t.text :tags, comment: "JSON array of tags for filtering and categorization"
+      t.integer :response_size_bytes, comment: "HTTP response body size in bytes"
       t.timestamps
     end
 
@@ -131,6 +132,10 @@ RailsPulse::Schema ||= lambda do |connection|
       t.string :codebase_location, comment: "File and line number (e.g., app/models/user.rb:25)"
       t.float :start_time, null: false, default: 0.0, comment: "Operation start time in milliseconds"
       t.timestamp :occurred_at, null: false, comment: "When the request started"
+      t.integer :row_count, comment: "Number of rows returned (SQL operations, Rails 7.1+)"
+      t.boolean :cache_hit, comment: "Whether a cache_read operation hit the cache"
+      t.text :repeated_query_group, comment: "Normalized SQL key identifying an N+1 group"
+      t.integer :repetition_count, comment: "Number of times this query pattern repeated in the request"
       t.timestamps
     end
 
@@ -154,7 +159,7 @@ RailsPulse::Schema ||= lambda do |connection|
       t.string :period_type, null: false, comment: "Aggregation period type: hour, day, week, month"
 
       # Polymorphic association to handle both routes and queries
-      t.references :summarizable, polymorphic: true, null: false, index: false, comment: "Link to Route or Query"
+      t.references :summarizable, polymorphic: true, null: false, index: true, comment: "Link to Route or Query"
       # This creates summarizable_type (e.g., 'RailsPulse::Route', 'RailsPulse::Query')
       # and summarizable_id (route_id or query_id)
 

data/lib/rails_pulse/version.rb

@@ -1,3 +1,3 @@
 module RailsPulse
-  VERSION = "0.3.0.pre.2"
+  VERSION = "0.3.1"
 end

data/lib/rails_pulse.rb

@@ -16,7 +16,11 @@ module RailsPulse
     end
 
     def logger
-      @logger ||= ActiveSupport::TaggedLogging.new(Rails.logger).tagged("RailsPulse")
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        @logger ||= ActiveSupport::TaggedLogging.new(Rails.logger).tagged("RailsPulse")
+      else
+        Logger.new($stdout)
+      end
     end
 
     def clear_metric_cache!

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_pulse
 version: !ruby/object:Gem::Version
-  version: 0.3.0.pre.2
+  version: 0.3.1
 platform: ruby
 authors:
-- Rails Pulse
+- Scott Harvey
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-23 00:00:00.000000000 Z
+date: 2026-05-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -190,9 +190,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Ruby on Rails performance monitoring tool that provides insights into
-  your application's performance, helping you identify bottlenecks and optimize your
-  code for better efficiency.
+description: Self-hosted performance monitoring engine for Rails apps. Tracks slow
+  requests, N+1 queries, and SQL performance. All data stays in your own database
+  — no third-party cloud required.
 email:
 - hey@railspulse.com
 executables:
@@ -204,8 +204,11 @@ files:
 - README.md
 - Rakefile
 - app/assets/images/rails_pulse/dashboard.png
+- app/assets/images/rails_pulse/query-show.png
 - app/assets/images/rails_pulse/rails-pulse-logo.png
+- app/assets/images/rails_pulse/request-show.png
 - app/assets/images/rails_pulse/request.png
+- app/assets/images/rails_pulse/route-show.png
 - app/assets/stylesheets/rails_pulse/application.css
 - app/assets/stylesheets/rails_pulse/components/alert.css
 - app/assets/stylesheets/rails_pulse/components/badge.css
@@ -433,7 +436,7 @@ files:
 - config/routes.rb
 - db/rails_pulse_migrate/20260417000001_add_diagnostic_fields.rb
 - db/rails_pulse_migrate/20260419000001_add_p95_p99_duration_to_rails_pulse_jobs.rb
-- db/rails_pulse_migrate/20260420000001_expand_normalized_sql_column.rb
+- db/rails_pulse_migrate/20260420000001_expand_normalized_query_column.rb
 - db/rails_pulse_schema.rb
 - exe/rails_pulse_server
 - lib/generators/rails_pulse/base_methods.rb
@@ -498,13 +501,15 @@ files:
 - vendor/css-zero/utilities.css
 - vendor/css-zero/variables.css
 - vendor/flatpickr.css
-homepage: https://www.railspulse.com
+homepage: https://railspulse.com
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://www.railspulse.com
+  homepage_uri: https://railspulse.com
   source_code_uri: https://github.com/railspulse/rails_pulse
+  changelog_uri: https://github.com/railspulse/rails_pulse/blob/main/CHANGELOG.md
+  documentation_uri: https://railspulse.com/documentation/installation
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -523,5 +528,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Ruby on Rails performance monitoring tool.
+summary: Self-hosted performance monitoring engine for Rails apps.
 test_files: []