rails_pulse 0.1.3 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11728d425611e7ab3a9edb171f05638a783d1c8d3ded8dff112bb615e8a18d11
-  data.tar.gz: 3e16c2d59f4f4bd8d2df49625d9f6005edc98dec701212a6052f4abfd1cac6f3
+  metadata.gz: a8ed469f307dd71e912b46a4da0a0daa60abbdc262a8dbd12604db00a66335fe
+  data.tar.gz: 8af5a6bf946a86e1bc277c1d719100ace739bb429c07969fd1e4ec31887d6f70
 SHA512:
-  metadata.gz: 443645ed917ef9beea2d642ff8c4a7d2e57cc87559a09e74dfd75d20d18fb0ff11040eac6e825f3ff0af35637ea23757c88b24e78f35e32f64a7660168aa940a
-  data.tar.gz: d11227a7a11c24bff167104e712f9d075a394130a196938ed71b360e6cbc82a8f930672187b92d0009ed5c14fee882ff23d3d88a3df25b1ddeff3a8839452b5b
+  metadata.gz: eceb3af7e713b6049688e50a8fd79af7b2f09c7720158c8d15257235b0c7488ebe7c0eccfaab3cd5dfb5923f80e9a8bd8693d0a9fb2f4e021aca8846c4ac435c
+  data.tar.gz: f982a50256d99968eb68fee89e6380d3f75511e6c3e8e878ddca375919f6a68a201f9ce46c6868e2425c127ae1862ca0d1895b0e01afea89a9af6a4e85d7f0f9

data/README.md

@@ -25,6 +25,10 @@
 - [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)
@@ -58,6 +62,11 @@ Rails Pulse is a comprehensive performance monitoring and debugging gem that pro
 - Smart caching with minimal performance overhead
 - Multiple database support (SQLite, PostgreSQL, MySQL)
 
+### Organization & Filtering
+- Flexible tagging system for routes, requests, and queries
+- Filter performance data by custom tags
+- Organize monitoring data by environment, priority, or custom categories
+
 ## Screenshots
 
 <table>
@@ -87,15 +96,22 @@ bundle install
 Generate the installation files:
 
 ```bash
+# Install with single database setup (default - recommended)
 rails generate rails_pulse:install
-```
 
-Load the database schema:
+# Or install with separate database setup
+rails generate rails_pulse:install --database=separate
+```
 
+**For single database setup (default):**
 ```bash
-rails db:prepare
+rails db:migrate    # Creates Rails Pulse tables in your main database
 ```
 
+**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:
 
 ```ruby
@@ -122,6 +138,10 @@ Rails Pulse automatically starts collecting performance data once installed. Acc
 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
+
 ### Basic Configuration
 
 Customize Rails Pulse in `config/initializers/rails_pulse.rb`:
@@ -165,6 +185,9 @@ RailsPulse.configure do |config|
   config.ignored_requests = []  # Array of request patterns to ignore
   config.ignored_queries = []   # Array of query patterns 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 = 2.weeks # Delete records older than this
@@ -232,6 +255,72 @@ config.authentication_method = proc {
 }
 ```
 
+## Tagging System
+
+Rails Pulse includes a flexible tagging system that allows you to categorize and organize your performance data. Tag routes, requests, and queries 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, or query 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")
+
+# 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.
@@ -287,20 +376,36 @@ RailsPulse::CleanupJob.perform_later
 
 ## Separate Database Support
 
-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.
+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
 
-Use a separate database when you want:
+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
 
-**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:
+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|
@@ -356,17 +461,30 @@ production:
     pool: 5
 ```
 
-### Schema Loading
+### Installation Steps
 
-After installation, load the Rails Pulse database schema:
+**For separate database setup:**
 
-```bash
-rails db:prepare
-```
+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:**
 
-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
+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/`
 
 ## Testing
 

data/Rakefile

@@ -1,109 +1,341 @@
 require "bundler/setup"
+require "bundler/gem_tasks"
 
 # Load environment variables from .env file
 require "dotenv/load" if File.exist?(".env")
 
 APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
 load "rails/tasks/engine.rake"
-load "rails/tasks/statistics.rake"
 
-require "bundler/gem_tasks"
+desc "Setup database for testing"
+task :test_setup do
+  database = ENV['DB'] || 'sqlite3'
 
-# Test tasks
-namespace :test do
-  desc "Run unit tests (models, helpers, services, instrumentation)"
-  task :unit do
-    sh "rails test test/models test/helpers test/services test/support test/instrumentation"
-  end
+  puts "\n" + "=" * 50
+  puts "🛠️  Rails Pulse Test Setup"
+  puts "=" * 50
+  puts "Database: #{database.upcase}"
+  puts "=" * 50
+  puts
+
+  begin
+    # Remove schema.rb to ensure clean migration
+    schema_file = "test/dummy/db/schema.rb"
+    if File.exist?(schema_file)
+      puts "🧹 Removing existing schema.rb file..."
+      File.delete(schema_file)
+    end
 
-  desc "Run functional tests (controllers)"
-  task :functional do
-    sh "rails test test/controllers"
+    case database.downcase
+    when 'sqlite3', 'sqlite'
+      puts "📦 Setting up SQLite database..."
+      sh "RAILS_ENV=test bin/rails db:drop db:create db:migrate"
+
+    when 'mysql2', 'mysql'
+      puts "🐬 Setting up MySQL database..."
+      sh "DB=mysql2 RAILS_ENV=test rails db:drop db:create db:migrate"
+
+    when 'postgresql', 'postgres'
+      puts "🐘 Setting up PostgreSQL database..."
+      sh "DB=postgresql RAILS_ENV=test rails db:drop db:create db:migrate"
+
+    else
+      puts "⚠️  Unknown database: #{database}"
+      puts "Supported databases: sqlite3, mysql2, postgresql"
+      exit 1
+    end
+
+    puts "\n✅ Database setup complete!"
+    puts "Ready to run: rake test"
+
+  rescue => e
+    puts "\n❌ Database setup failed!"
+    puts "Error: #{e.message}"
+    puts "\nTroubleshooting:"
+    puts "• Ensure #{database} is installed and running"
+    puts "• Check database credentials in test/dummy/config/database.yml"
+    puts "• Verify RAILS_ENV=test environment is configured"
+    exit 1
   end
+end
+
+desc "Run test suite"
+task :test do
+  database = ENV['DB'] || 'sqlite3'
 
-  desc "Run integration tests"
-  task :integration do
-    sh "rails test test/integration test/system"
+  # Get Rails version from Gemfile.lock or fallback
+  rails_version = begin
+    require 'rails'
+    Rails.version
+  rescue LoadError
+    # Try to get from Gemfile.lock
+    gemfile_lock = File.read('Gemfile.lock') rescue nil
+    if gemfile_lock && gemfile_lock.match(/rails \(([^)]+)\)/)
+      $1
+    else
+      'unknown'
+    end
   end
 
-  desc "Run all tests"
-  task :all do
-    sh "rails test"
+  puts "\n" + "=" * 50
+  puts "💛 Rails Pulse Test Suite"
+  puts "=" * 50
+  puts "Database: #{database.upcase}"
+  puts "Rails: #{rails_version}"
+  puts "=" * 50
+  puts
+
+  sh "rails test test/controllers test/helpers test/instrumentation test/jobs test/models test/services"
+end
+
+desc "Setup database for specific Rails version and database"
+task :test_setup_for_version, [ :database, :rails_version ] do |t, args|
+  database = args[:database] || ENV['DB'] || 'sqlite3'
+  rails_version = args[:rails_version] || 'rails-8-0'
+
+  puts "\n" + "=" * 50
+  puts "🛠️  Rails Pulse Test Setup"
+  puts "=" * 50
+  puts "Database: #{database.upcase}"
+  puts "Rails: #{rails_version.upcase.gsub('-', ' ')}"
+  puts "=" * 50
+  puts
+
+  begin
+    # Remove schema.rb to ensure clean migration
+    schema_file = "test/dummy/db/schema.rb"
+    if File.exist?(schema_file)
+      puts "🧹 Removing existing schema.rb file..."
+      File.delete(schema_file)
+    end
+
+    if rails_version == "rails-8-0" && database == "sqlite3"
+      # Use current default setup
+      puts "📦 Setting up #{database.upcase} database with Rails 8.0..."
+      sh "RAILS_ENV=test bin/rails db:drop db:create db:migrate"
+    else
+      # Use appraisal with specific database and Rails version
+      puts "📦 Setting up #{database.upcase} database with #{rails_version.upcase.gsub('-', ' ')}..."
+      sh "DB=#{database} bundle exec appraisal #{rails_version} rails db:drop db:create db:migrate RAILS_ENV=test"
+    end
+
+    puts "\n✅ Database setup complete for #{database.upcase} + #{rails_version.upcase.gsub('-', ' ')}!"
+
+  rescue => e
+    puts "\n❌ Database setup failed!"
+    puts "Error: #{e.message}"
+    exit 1
   end
+end
+
+desc "Test all database and Rails version combinations"
+task :test_matrix do
+  databases = %w[sqlite3 postgresql mysql2]
+  rails_versions = %w[rails-7-2 rails-8-0]
+
+  failed_combinations = []
+  total_combinations = databases.size * rails_versions.size
+  current = 0
+
+  # Check if system tests should be included
+  include_system_tests = ENV['BROWSER'] == 'true'
+  test_paths = "test/controllers test/helpers test/instrumentation test/jobs test/models test/services"
+  test_paths += " test/system" if include_system_tests
+
+  puts "\n" + "=" * 60
+  puts "🚀 Rails Pulse Full Test Matrix"
+  puts "=" * 60
+  puts "Testing #{total_combinations} combinations..."
+  puts "System tests: #{include_system_tests ? 'ENABLED (BROWSER=true)' : 'DISABLED (headless mode)'}"
+  puts "=" * 60
+
+  databases.each do |database|
+    rails_versions.each do |rails_version|
+      current += 1
 
-  desc "Run tests across all database and Rails version combinations (local only - CI uses sqlite3 + postgresql)"
-  task :matrix do
-    databases = [ "sqlite3", "postgresql", "mysql2" ]
-    rails_versions = [ "rails-7-2", "rails-8-0" ]
-
-    failed_combinations = []
-
-    databases.each do |database|
-      rails_versions.each do |rails_version|
-        puts "\n" + "=" * 80
-        puts "🧪 Local Testing: #{database.upcase} + #{rails_version.upcase}"
-        puts "(CI only tests SQLite3 + PostgreSQL for reliability)"
-        puts "=" * 80
-
-        begin
-          gemfile = "gemfiles/#{rails_version.gsub('-', '_')}.gemfile"
-
-          # Set environment variables
-          env_vars = {
-            "DB" => database,
-            "BUNDLE_GEMFILE" => gemfile,
-            "FORCE_DB_CONFIG" => "true"
-          }
-
-          # Add database-specific environment variables
-          case database
-          when "postgresql"
-            env_vars.merge!({
-              "POSTGRES_USERNAME" => ENV.fetch("POSTGRES_USERNAME", "postgres"),
-              "POSTGRES_PASSWORD" => ENV.fetch("POSTGRES_PASSWORD", ""),
-              "POSTGRES_HOST" => ENV.fetch("POSTGRES_HOST", "localhost"),
-              "POSTGRES_PORT" => ENV.fetch("POSTGRES_PORT", "5432")
-            })
-          when "mysql2"
-            env_vars.merge!({
-              "MYSQL_USERNAME" => ENV.fetch("MYSQL_USERNAME", "root"),
-              "MYSQL_PASSWORD" => ENV.fetch("MYSQL_PASSWORD", "password"),
-              "MYSQL_HOST" => ENV.fetch("MYSQL_HOST", "localhost"),
-              "MYSQL_PORT" => ENV.fetch("MYSQL_PORT", "3306")
-            })
-          end
-
-          # Build environment string
-          env_string = env_vars.map { |k, v| "#{k}=#{v}" }.join(" ")
-
-          # Run the test command
-          sh "#{env_string} bundle exec rails test:all"
-
-          puts "✅ PASSED: #{database} + #{rails_version}"
-
-        rescue => e
-          puts "❌ FAILED: #{database} + #{rails_version}"
-          puts "Error: #{e.message}"
-          failed_combinations << "#{database} + #{rails_version}"
+      puts "\n[#{current}/#{total_combinations}] Testing: #{database.upcase} + #{rails_version.upcase.gsub('-', ' ')}"
+      puts "-" * 50
+
+      begin
+        # First setup the database for this specific combination
+        Rake::Task[:test_setup_for_version].reenable
+        Rake::Task[:test_setup_for_version].invoke(database, rails_version)
+
+        # Then run the tests
+        if rails_version == "rails-8-0" && database == "sqlite3"
+          # Current default setup
+          sh "BROWSER=#{ENV['BROWSER']} rails test #{test_paths}"
+        else
+          # Use appraisal with specific database
+          sh "DB=#{database} BROWSER=#{ENV['BROWSER']} bundle exec appraisal #{rails_version} rails test #{test_paths}"
         end
+
+        puts "✅ PASSED: #{database} + #{rails_version}"
+
+      rescue => e
+        puts "❌ FAILED: #{database} + #{rails_version}"
+        puts "   Error: #{e.message}"
+        failed_combinations << "#{database} + #{rails_version}"
       end
     end
+  end
+
+  puts "\n" + "=" * 60
+  puts "🏁 Test Matrix Results"
+  puts "=" * 60
+
+  if failed_combinations.empty?
+    puts "🎉 All #{total_combinations} combinations passed!"
+  else
+    puts "✅ Passed: #{total_combinations - failed_combinations.size}/#{total_combinations}"
+    puts "❌ Failed combinations:"
+    failed_combinations.each { |combo| puts "   • #{combo}" }
+    exit 1
+  end
+end
 
-    puts "\n" + "=" * 80
-    puts "🏁 Local Test Matrix Results"
-    puts "(CI automatically tests SQLite3 + PostgreSQL only)"
-    puts "=" * 80
+desc "Pre-release testing with comprehensive checks"
+task :test_release do
+  puts "\n" + "=" * 70
+  puts "🚀 Rails Pulse Pre-Release Validation"
+  puts "=" * 70
+  puts
 
-    if failed_combinations.empty?
-      puts "✅ All combinations passed!"
+  failed_tasks = []
+  current_step = 0
+  total_steps = 7
+
+  # Step 1: Git status check
+  current_step += 1
+  begin
+    puts "\n[#{current_step}/#{total_steps}] Checking git status..."
+    puts "-" * 70
+
+    git_status = `git status --porcelain`.strip
+    if !git_status.empty?
+      puts "❌ Git working directory is not clean!"
+      puts "\nUncommitted changes:"
+      puts git_status
+      puts "\nPlease commit or stash your changes before running pre-release tests."
+      failed_tasks << "git_status_check"
     else
-      puts "❌ Failed combinations:"
-      failed_combinations.each { |combo| puts "  - #{combo}" }
-      exit 1
+      puts "✅ Git working directory is clean"
     end
+  rescue => e
+    puts "⚠️  Warning: Could not check git status (#{e.message})"
+  end
+
+  # Step 2: RuboCop linting
+  current_step += 1
+  begin
+    puts "\n[#{current_step}/#{total_steps}] Running RuboCop linting..."
+    puts "-" * 70
+    sh "bundle exec rubocop"
+    puts "✅ Code style checks passed!"
+  rescue => e
+    puts "❌ RuboCop linting failed!"
+    puts "   Error: #{e.message}"
+    failed_tasks << "rubocop"
+  end
+
+  # Step 3: Install Node dependencies
+  current_step += 1
+  begin
+    puts "\n[#{current_step}/#{total_steps}] Installing Node dependencies..."
+    puts "-" * 70
+    sh "npm install"
+    puts "✅ Node dependencies installed!"
+  rescue => e
+    puts "❌ npm install failed!"
+    puts "   Error: #{e.message}"
+    failed_tasks << "npm_install"
+  end
+
+  # Step 4: Build and verify assets
+  current_step += 1
+  begin
+    puts "\n[#{current_step}/#{total_steps}] Building production assets..."
+    puts "-" * 70
+    sh "npm run build"
+
+    # Verify assets were built
+    assets_dir = "public/rails-pulse-assets"
+    if Dir.exist?(assets_dir) && !Dir.empty?(assets_dir)
+      puts "✅ Assets built successfully!"
+      puts "   Location: #{assets_dir}"
+    else
+      puts "❌ Assets directory is missing or empty!"
+      failed_tasks << "asset_build_verification"
+    end
+  rescue => e
+    puts "❌ Asset building failed!"
+    puts "   Error: #{e.message}"
+    failed_tasks << "npm_build"
+  end
+
+  # Step 5: Verify gem builds
+  current_step += 1
+  begin
+    puts "\n[#{current_step}/#{total_steps}] Verifying gem builds correctly..."
+    puts "-" * 70
+    sh "gem build rails_pulse.gemspec"
+
+    # Clean up the built gem
+    built_gems = Dir.glob("rails_pulse-*.gem")
+    built_gems.each { |gem_file| File.delete(gem_file) }
+
+    puts "✅ Gem builds successfully!"
+  rescue => e
+    puts "❌ Gem build failed!"
+    puts "   Error: #{e.message}"
+    failed_tasks << "gem_build"
+  end
+
+  # Step 6: Run generator tests
+  current_step += 1
+  begin
+    puts "\n[#{current_step}/#{total_steps}] Running generator tests..."
+    puts "-" * 70
+    sh "./bin/test_generators"
+    puts "✅ Generator tests passed!"
+  rescue => e
+    puts "❌ Generator tests failed!"
+    puts "   Error: #{e.message}"
+    failed_tasks << "test_generators"
+  end
+
+  # Step 7: Run full test matrix with system tests
+  current_step += 1
+  begin
+    puts "\n[#{current_step}/#{total_steps}] Running full test matrix with system tests..."
+    puts "-" * 70
+    sh "BROWSER=true rake test_matrix"
+    puts "✅ Test matrix passed!"
+  rescue => e
+    puts "❌ Test matrix failed!"
+    puts "   Error: #{e.message}"
+    failed_tasks << "test_matrix"
+  end
+
+  # Print final results
+  puts "\n" + "=" * 70
+  puts "🏁 Pre-Release Validation Results"
+  puts "=" * 70
+
+  if failed_tasks.empty?
+    puts "🎉 All pre-release checks passed!"
+    puts "\n✅ Ready for release!"
+    puts "\nNext steps:"
+    puts "  1. Update version in lib/rails_pulse/version.rb"
+    puts "  2. Update Gemfile.lock files for all Rails versions"
+    puts "  3. Follow the release process in docs/releasing.md"
+  else
+    puts "❌ Failed checks (#{failed_tasks.size}/#{total_steps}):"
+    failed_tasks.each { |task| puts "   • #{task}" }
+    puts "\n⚠️  Fix these issues before releasing."
+    exit 1
   end
 end
 
-# Override default test task
-desc "Run all tests"
-task test: "test:all"
+
+task default: :test