rails_pulse 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 418546b7a8b0324941402583074cd0a569d51ef4b8e4b0d02261957d16c6d2ab
-  data.tar.gz: 7d027dafdf22c964a503a4a8e66d6d7c0e7af8f3d299c3acd2c65b2a1bd63705
+  metadata.gz: 7c6b5219e5da388e0ec200a6382527d227ab0e2ee20faa11e3ce8e49992ce6b8
+  data.tar.gz: 1a713357c2ab7eb454b269f358c9b9fb1939eef9e3d17c8cb7cf9a12cab8206c
 SHA512:
-  metadata.gz: 331a413a83ab2c81f43ee796676eb127dd0541f14912bba66982142ac3cfe5d2276e9c0aecd67aeb11e2219ffe66ad3f1f8c0791e7b68e5f1bba5f517072cdd6
-  data.tar.gz: 6d1885f4af1c42bef1caac9044aa72b514de7669536e4bf7f58b23e63ebbbddd32040106b72424d61bc7e7068241d0de1ce68816d6fe9b368e4279b4f62e6adf
+  metadata.gz: cf37a0c4d1ac19450ae702ee22b4f460d8b16528a00603d1cbb0fbad6ff5d6b8caf1dca90ff9ec0834683f56651af76ec0d14465c244d3e95482c76a8fcf9ccc
+  data.tar.gz: f150bd31c92462f5c1594368816aaaa60fe6e17ec4e4e0cb67d8b0ff7c0732be9d544df040548c6c80050fea6e66d6f21cf960dcec1b4af6bec4cbb4c318bb24

data/README.md

@@ -6,7 +6,7 @@
   **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-8.0+-blue)
+  ![Rails Version](https://img.shields.io/badge/Rails-7.2+-blue)
   ![License](https://img.shields.io/badge/License-MIT-green)
   ![Ruby Version](https://img.shields.io/badge/Ruby-3.3+-red)
 </div>
@@ -25,16 +25,14 @@
 - [Authentication](#authentication)
   - [Authentication Setup](#authentication-setup)
   - [Authentication Examples](#authentication-examples)
-  - [Security Considerations](#security-considerations)
 - [Data Management](#data-management)
   - [Cleanup Strategies](#cleanup-strategies)
   - [Cleanup Configuration](#cleanup-configuration)
   - [Manual Cleanup Operations](#manual-cleanup-operations)
-  - [How Cleanup Works](#how-cleanup-works)
-- [Multiple Database Support](#multiple-database-support)
+- [Separate Database Support](#separate-database-support)
   - [Configuration](#configuration)
   - [Database Configuration](#database-configuration)
-  - [Migration](#migration)
+  - [Schema Loading](#schema-loading)
 - [Testing](#testing)
 - [Technology Stack](#technology-stack)
 - [Advantages Over Other Solutions](#advantages-over-other-solutions)
@@ -44,33 +42,17 @@
 
 ## Introduction
 
-Rails Pulse is a comprehensive performance monitoring and debugging gem that provides real-time 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.
-
-**Why Rails Pulse?**
-
-- **Visual**: Beautiful, responsive dashboards with actionable insights
-- **Comprehensive**: Monitors requests, database queries, and application operations
-- **Real-time**: Live performance metrics
-- **Zero Configuration**: Works out of the box with sensible defaults
-- **Lightweight**: Minimal performance overhead in production
-- **Asset Independent**: Pre-compiled assets work with any Rails build system
-- **CSP Compliant**: Secure by default with Content Security Policy support
+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.
 
 ## Features
 
-### 🎯 **Performance Monitoring**
+### 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
 - Week-over-week trend analysis with visual indicators
 
-### 🔒 **Production Ready**
-- Content Security Policy (CSP) compliant with pre-compiled assets
-- Flexible authentication system with multiple authentication methods
-- Automatic data cleanup with configurable retention policies
-- Zero build dependencies - works with any Rails setup
-
-### ⚡ **Developer Experience**
+### Developer Experience
 - Zero configuration setup with sensible defaults
 - Beautiful responsive interface with dark/light mode
 - Smart caching with minimal performance overhead
@@ -102,22 +84,30 @@ Generate the installation files:
 rails generate rails_pulse:install
 ```
 
-Run the migrations:
+Load the database schema:
 
 ```bash
-rails db:migrate
+rails db:prepare
 ```
 
 Add the Rails Pulse route to your application:
 
 ```ruby
-# config/routes.rb
 Rails.application.routes.draw do
   mount RailsPulse::Engine => "/rails_pulse"
-  # ... your other routes
 end
 ```
 
+Schedule background jobs:
+
+```ruby
+# Schedule to run 5 minutes past every hour
+RailsPulse::SummaryJob.perform_later
+
+# Schedule to run daily
+RailsPulse::CleanupJob.perform_later
+```
+
 ### Quick Setup
 
 Rails Pulse automatically starts collecting performance data once installed. Access your monitoring dashboard at:
@@ -135,14 +125,14 @@ RailsPulse.configure do |config|
   # Enable or disable Rails Pulse
   config.enabled = true
 
-  # Set performance thresholds for routes (in milliseconds)
+  # Set performance thresholds for route response times (in milliseconds)
   config.route_thresholds = {
     slow: 500,
     very_slow: 1500,
     critical: 3000
   }
 
-  # Set performance thresholds for requests (in milliseconds)
+  # Set performance thresholds for request response times (in milliseconds)
   config.request_thresholds = {
     slow: 700,
     very_slow: 2000,
@@ -157,8 +147,8 @@ RailsPulse.configure do |config|
   }
 
   # Asset tracking configuration
-  config.track_assets = false  # Ignore asset requests by default
-  config.custom_asset_patterns = []  # Additional asset patterns to ignore
+  config.track_assets = false       # Ignore asset requests by default
+  config.custom_asset_patterns = [] # Additional asset patterns to ignore
 
   # Rails Pulse mount path (optional)
   # Specify if Rails Pulse is mounted at a custom path to prevent self-tracking
@@ -171,7 +161,7 @@ RailsPulse.configure do |config|
 
   # Data cleanup
   config.archiving_enabled = true        # Enable automatic cleanup
-  config.full_retention_period = 2.weeks  # Delete records older than this
+  config.full_retention_period = 2.weeks # Delete records older than this
   config.max_table_records = {           # Maximum records per table
     rails_pulse_requests: 10000,
     rails_pulse_operations: 50000,
@@ -179,10 +169,6 @@ RailsPulse.configure do |config|
     rails_pulse_queries: 500
   }
 
-  # Metric caching for performance
-  config.component_cache_enabled = true
-  config.component_cache_duration = 1.day
-
   # Multiple database support (optional)
   # Uncomment to store Rails Pulse data in a separate database
   # config.connects_to = {
@@ -219,7 +205,7 @@ end
 
 Rails Pulse works with any authentication system. Here are common patterns:
 
-#### **Devise with Admin Role**
+#### Devise with Admin Role
 
 ```ruby
 config.authentication_method = proc {
@@ -229,36 +215,7 @@ config.authentication_method = proc {
 }
 ```
 
-#### **Custom Session-based Authentication**
-
-```ruby
-config.authentication_method = proc {
-  unless session[:user_id] && User.find_by(id: session[:user_id])&.admin?
-    redirect_to main_app.login_path, alert: "Please log in as an admin"
-  end
-}
-```
-
-#### **HTTP Basic Authentication**
-
-```ruby
-config.authentication_method = proc {
-  authenticate_or_request_with_http_basic do |username, password|
-    username == ENV['RAILS_PULSE_USERNAME'] &&
-    password == ENV['RAILS_PULSE_PASSWORD']
-  end
-}
-```
-
-#### **Warden Authentication**
-
-```ruby
-config.authentication_method = proc {
-  warden.authenticate!(scope: :admin)
-}
-```
-
-#### **Custom Authorization Logic**
+#### Custom Authorization Logic
 
 ```ruby
 config.authentication_method = proc {
@@ -269,16 +226,6 @@ config.authentication_method = proc {
 }
 ```
 
-### Security Considerations
-
-- **Production Security**: Always enable authentication in production environments
-- **Admin-only Access**: Limit access to administrators or authorized personnel
-- **Environment Variables**: Use environment variables for credentials, never hardcode
-- **HTTPS Required**: Always use HTTPS in production when authentication is enabled
-- **Regular Access Review**: Periodically review who has access to monitoring data
-
-**Important**: The authentication method runs in the context of the Rails Pulse ApplicationController, giving you access to all standard Rails controller methods like `redirect_to`, `render`, `session`, and any methods from your host application's authentication system.
-
 ## Data Management
 
 Rails Pulse provides data cleanup to prevent your monitoring database from growing indefinitely while preserving essential performance insights.
@@ -329,28 +276,22 @@ rails rails_pulse:cleanup_stats
 
 **Schedule automated cleanup:**
 ```ruby
-# Using whenever gem or similar scheduler
 RailsPulse::CleanupJob.perform_later
 ```
 
-### How Cleanup Works
+## Separate Database Support
 
-1. **Time-based Phase**: Delete all records older than `full_retention_period`
-2. **Count-based Phase**: If tables still exceed limits, delete oldest remaining records
-3. **Safe Deletion**: Respects foreign key constraints (operations → requests → queries/routes)
-4. **Comprehensive Logging**: Detailed cleanup statistics and operation logs
+Rails Pulse supports storing performance monitoring data in a **separate database**. By default, Rails Pulse stores data in your main application database alongside your existing tables.
 
-This two-phase approach ensures you keep the most valuable recent performance data while maintaining manageable database sizes.
-
-## Multiple Database Support
-
-Rails Pulse supports storing performance monitoring data in a separate database. This is particularly useful for:
+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
 
+**For shared database setup (default)**, no database configuration is needed - simply run `rails db:prepare` after installation.
+
 ### Configuration
 
 To use a separate database, configure the `connects_to` option in your Rails Pulse initializer:
@@ -380,6 +321,7 @@ production:
   rails_pulse:
     adapter: sqlite3
     database: storage/rails_pulse_production.sqlite3
+    migrations_paths: db/rails_pulse_migrate
     pool: 5
     timeout: 5000
 
@@ -392,6 +334,7 @@ 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
@@ -403,35 +346,31 @@ production:
     username: rails_pulse_user
     password: <%= Rails.application.credentials.dig(:rails_pulse, :database_password) %>
     host: localhost
+    migrations_paths: db/rails_pulse_migrate
     pool: 5
 ```
 
-### Migration
+### Schema Loading
 
-When using a separate database, run migrations targeting the Rails Pulse database:
+After installation, load the Rails Pulse database schema:
 
 ```bash
-# Run Rails Pulse migrations on the configured database
-rails db:migrate
-
-# If you need to run migrations on a specific database
-RAILS_ENV=production rails db:migrate
+rails db:prepare
 ```
 
-**Note:** Rails Pulse maintains full backward compatibility. If no `connects_to` configuration is provided, all data will be stored in your main application database as before.
+This command works for both:
+- Shared database setup (default): Loads tables into your main application database
+- Separate database setup: Automatically loads tables into your configured Rails Pulse database
 
 ## Testing
 
-Rails Pulse includes a comprehensive test suite designed for speed and reliability across multiple databases (SQLite, MySQL, PostgreSQL) and Rails versions.
+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)
+# Run all tests (unit, functional, integration, instrumentation)
 rails test:all
-
-# Run tests with speed optimizations
-rails test:fast
 ```
 
 ### Running Individual Test Types
@@ -452,83 +391,46 @@ rails test:integration
 ```bash
 # Run a specific test file
 rails test test/models/rails_pulse/request_test.rb
-
-# Run controller tests
-rails test test/controllers/rails_pulse/dashboard_controller_test.rb
-
-# Run helper tests
-rails test test/helpers/rails_pulse/application_helper_test.rb
-
-# Run factory verification tests
-rails test test/factories_test.rb
 ```
 
-### Multi-Rails Version Testing
+### Multi-Database and Rails Version Testing
 
-Test against multiple Rails versions using Appraisal:
+Test against multiple databases and Rails versions using the matrix task:
 
 ```bash
-# Install dependencies for all Rails versions
-bundle exec appraisal install
-
-# Run tests against all Rails versions
-bundle exec appraisal rails test:all
-
-# Run tests against specific Rails version
-bundle exec appraisal rails-7-1 rails test:unit
+# Test all database and Rails version combinations locally
+rails test:matrix
 ```
 
-### Test Performance Features
-
-- **In-memory SQLite**: Unit and functional tests use fast in-memory databases
-- **Transaction rollback**: Tests use database transactions for fast cleanup
-- **Stubbed dependencies**: External calls and expensive operations are stubbed
-- **Parallel execution**: Tests run in parallel when supported
-
-### Database Testing
-
-Rails Pulse supports testing with multiple database adapters using simplified Rake tasks:
-
-```bash
-# Quick Commands (Recommended)
-rails test:sqlite        # Test with SQLite (default)
-rails test:postgresql    # Test with PostgreSQL
-rails test:mysql         # Test with MySQL
-
-# Test Matrix (before pushing)
-rails test:matrix        # Test SQLite + PostgreSQL
-rails test:matrix_full   # Test all databases (SQLite + PostgreSQL + MySQL)
-```
+This command tests all combinations locally:
+- **Databases**: SQLite3, PostgreSQL, MySQL2 (local testing only)
+- **Rails versions**: 7.2, 8.0
 
-#### Development Environment Setup
+**Note**: CI only tests SQLite3 + PostgreSQL for reliability. MySQL is available for local testing but excluded from CI due to flakiness.
 
-1. **Set up git hooks (optional but recommended):**
-   ```bash
-   ./scripts/setup-git-hooks
-   ```
-   This installs a pre-commit hook that runs RuboCop before each commit.
+### Development Environment Setup
 
-2. **Copy the environment template:**
+1. **Copy the environment template:**
    ```bash
    cp .env.example .env
    ```
 
-3. **Configure your database credentials in `.env`:**
+2. **Configure your database credentials in `.env` (for local multi-database testing):**
    ```bash
-   # PostgreSQL Configuration
+   # PostgreSQL Configuration (used in CI + local)
    POSTGRES_USERNAME=your_username
    POSTGRES_PASSWORD=your_password
    POSTGRES_HOST=localhost
    POSTGRES_PORT=5432
 
-   # MySQL Configuration
+   # MySQL Configuration (local testing only)
    MYSQL_USERNAME=root
    MYSQL_PASSWORD=your_password
    MYSQL_HOST=localhost
    MYSQL_PORT=3306
    ```
 
-4. **Create test databases:**
+3. **Create test databases:**
    ```bash
    # PostgreSQL
    createdb rails_pulse_test
@@ -537,32 +439,32 @@ rails test:matrix_full   # Test all databases (SQLite + PostgreSQL + MySQL)
    mysql -u root -p -e "CREATE DATABASE rails_pulse_test;"
    ```
 
-#### Manual Commands
-If you prefer the explicit approach:
+### Manual Database Testing
+
+Test individual databases locally:
 
 ```bash
-# Test with SQLite (default, uses in-memory database)
+# Test with SQLite (default)
 rails test:all
 
-# Test with PostgreSQL (requires local PostgreSQL setup)
-DATABASE_ADAPTER=postgresql FORCE_DB_CONFIG=true rails test:all
+# Test with PostgreSQL  
+DB=postgresql FORCE_DB_CONFIG=true rails test:all
 
-# Test with MySQL (requires MySQL setup and mysql2 gem compilation)
-DATABASE_ADAPTER=mysql FORCE_DB_CONFIG=true rails test:all
+# Test with MySQL (local only)
+DB=mysql2 FORCE_DB_CONFIG=true rails test:all
 ```
 
-**Note**: Database switching is disabled by default for stability. The Rake tasks automatically handle the `FORCE_DB_CONFIG=true` requirement.
+### CI Testing
 
-**MySQL Testing**: MySQL testing requires:
-- MySQL server running locally with a `rails_pulse_test` database
-- Successful compilation of the `mysql2` gem (may require system dependencies like `zstd`)
-- CI environments come pre-configured, but local setup may require additional dependencies
+GitHub Actions CI automatically tests:
+- **Databases**: SQLite3, PostgreSQL only (MySQL excluded for reliability)
+- **Rails versions**: 7.2, 8.0
+- **Environment**: Uses memory SQLite and PostgreSQL service
 
-### Quick Testing Before Push
-```bash
-# Recommended: Test the same databases as CI
-rails test:matrix
-```
+**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
 
@@ -602,12 +504,6 @@ Rails Pulse is built using modern, battle-tested technologies that ensure reliab
 - **Customizable**: Full control over metrics, thresholds, and interface
 - **Asset Independence**: Works with any Rails build system (Sprockets, esbuild, Webpack, Vite)
 
-### **vs. Built-in Rails Logging**
-- **Visual Interface**: Beautiful dashboards instead of log parsing
-- **Structured Data**: Queryable metrics instead of text logs
-- **Historical Analysis**: Persistent storage with trend analysis
-- **Real-time Monitoring**: Live updates and health scoring
-
 ### **vs. Custom Monitoring Solutions**
 - **Batteries Included**: Complete monitoring solution out of the box
 - **Proven Architecture**: Built on Rails best practices
@@ -632,7 +528,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 <div align="center">
   <strong>Built with ❤️ for the Rails community</strong>
 
-  [Documentation](https://github.com/scottharvey/rails_pulse/wiki) •
-  [Issues](https://github.com/scottharvey/rails_pulse/issues) •
+  [Documentation](https://github.com/railspulse/rails_pulse/wiki) •
+  [Issues](https://github.com/railspulse/rails_pulse/issues) •
   [Contributing](CONTRIBUTING.md)
 </div>