findbug 0.2.0

data/lib/findbug/tasks/findbug.rake

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+# Findbug Rake Tasks
+#
+# These tasks help with maintenance and debugging.
+# Run `rake -T findbug` to see all available tasks.
+#
+
+namespace :findbug do
+  desc "Show Findbug configuration and status"
+  task status: :environment do
+    config = Findbug.config
+
+    puts "\n=== Findbug Status ==="
+    puts ""
+    puts "Enabled:            #{Findbug.enabled? ? 'Yes' : 'No'}"
+    puts "Environment:        #{config.environment}"
+    puts "Release:            #{config.release || '(not set)'}"
+    puts ""
+
+    puts "--- Error Capture ---"
+    puts "Sample Rate:        #{(config.sample_rate * 100).round(1)}%"
+    puts "Ignored Exceptions: #{config.ignored_exceptions.map(&:name).join(', ').presence || '(none)'}"
+    puts ""
+
+    puts "--- Performance ---"
+    puts "Performance Enabled:  #{config.performance_enabled ? 'Yes' : 'No'}"
+    puts "Performance Sample:   #{(config.performance_sample_rate * 100).round(1)}%"
+    puts "Slow Request Threshold: #{config.slow_request_threshold_ms}ms"
+    puts "Slow Query Threshold:   #{config.slow_query_threshold_ms}ms"
+    puts ""
+
+    puts "--- Storage ---"
+    puts "Redis URL:          #{config.redis_url.gsub(/:[^@]+@/, ':***@')}" # Hide password
+    puts "Redis Pool Size:    #{config.redis_pool_size}"
+    puts "Retention Days:     #{config.retention_days}"
+    puts ""
+
+    puts "--- Dashboard ---"
+    puts "Dashboard Enabled:  #{config.web_enabled? ? 'Yes' : 'No'}"
+    puts "Dashboard Path:     #{config.web_path}" if config.web_enabled?
+    puts ""
+
+    puts "--- Alerts ---"
+    if config.alerts.any_enabled?
+      config.alerts.enabled_channels.each do |name, _|
+        puts "  #{name}: enabled"
+      end
+    else
+      puts "(no alerts configured)"
+    end
+
+    puts ""
+
+    # Show Redis buffer stats if available
+    if Findbug.enabled?
+      puts "--- Buffer Status ---"
+      begin
+        stats = Findbug::Storage::RedisBuffer.stats
+        puts "Error Queue Length:       #{stats[:error_queue_length]}"
+        puts "Performance Queue Length: #{stats[:performance_queue_length]}"
+        puts "Circuit Breaker State:    #{stats[:circuit_breaker_state]}"
+        puts "Circuit Breaker Failures: #{stats[:circuit_breaker_failures]}"
+      rescue StandardError => e
+        puts "Could not fetch buffer stats: #{e.message}"
+      end
+    end
+
+    puts "\n"
+  end
+
+  desc "Clear all Findbug data from Redis buffers"
+  task clear_buffers: :environment do
+    puts "Clearing Findbug Redis buffers..."
+    Findbug::Storage::RedisBuffer.clear!
+    puts "Done!"
+  end
+
+  desc "Flush Redis buffers to database immediately"
+  task flush: :environment do
+    puts "Flushing Findbug buffers to database..."
+
+    require_relative "../jobs/persist_job"
+
+    error_count = 0
+    perf_count = 0
+
+    loop do
+      events = Findbug::Storage::RedisBuffer.pop_errors(100)
+      break if events.empty?
+
+      Findbug::Jobs::PersistJob.persist_errors(events)
+      error_count += events.size
+    end
+
+    loop do
+      events = Findbug::Storage::RedisBuffer.pop_performance(100)
+      break if events.empty?
+
+      Findbug::Jobs::PersistJob.persist_performance(events)
+      perf_count += events.size
+    end
+
+    puts "Flushed #{error_count} error events and #{perf_count} performance events."
+  end
+
+  desc "Run cleanup to remove old records"
+  task cleanup: :environment do
+    puts "Running Findbug cleanup..."
+
+    require_relative "../jobs/cleanup_job"
+    Findbug::Jobs::CleanupJob.perform_now
+
+    puts "Done!"
+  end
+
+  desc "Test error capture by raising a test exception"
+  task test: :environment do
+    puts "Testing Findbug error capture..."
+
+    # Capture a test exception
+    begin
+      raise "Findbug Test Exception - #{Time.now}"
+    rescue StandardError => e
+      Findbug.capture_exception(e, test: true)
+      puts "Test exception captured!"
+    end
+
+    # Wait for async write
+    sleep 0.5
+
+    # Check if it made it to Redis
+    stats = Findbug::Storage::RedisBuffer.stats
+    puts "Error queue length: #{stats[:error_queue_length]}"
+
+    if stats[:error_queue_length].positive?
+      puts "\nTest passed! Exception was captured."
+    else
+      puts "\nTest may have failed. Check configuration."
+    end
+  end
+
+  namespace :db do
+    desc "Show database record counts"
+    task stats: :environment do
+      puts "\n=== Findbug Database Stats ==="
+
+      if defined?(Findbug::ErrorEvent)
+        total_errors = Findbug::ErrorEvent.count
+        unresolved = Findbug::ErrorEvent.where(status: "unresolved").count
+        puts "Total Errors:      #{total_errors}"
+        puts "Unresolved:        #{unresolved}"
+      else
+        puts "ErrorEvent model not loaded"
+      end
+
+      if defined?(Findbug::PerformanceEvent)
+        total_perf = Findbug::PerformanceEvent.count
+        puts "Performance Events: #{total_perf}"
+      else
+        puts "PerformanceEvent model not loaded"
+      end
+
+      puts ""
+    end
+  end
+end

data/lib/findbug/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Findbug
+  VERSION = "0.2.0"
+end

data/lib/findbug.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require_relative "findbug/version"
+require_relative "findbug/configuration"
+
+# Findbug - Self-hosted error tracking and performance monitoring for Rails
+#
+# ARCHITECTURE OVERVIEW
+# =====================
+#
+# Findbug is designed with ONE critical goal: NEVER slow down your application.
+#
+# How we achieve this:
+#
+# 1. ASYNC WRITES
+#    When an error occurs, we don't write to the database immediately.
+#    Instead, we push to a Redis buffer in a background thread.
+#    This takes ~1-2ms and doesn't block your request.
+#
+# 2. BACKGROUND PERSISTENCE
+#    A periodic job (via ActiveJob or built-in thread) pulls events from Redis
+#    and batch-inserts them to the database. This happens outside your
+#    request cycle.
+#
+# 3. CIRCUIT BREAKER
+#    If Redis is down, we don't keep retrying and slowing down your app.
+#    The circuit breaker "opens" after 5 failures and stops attempting
+#    writes for 30 seconds.
+#
+# 4. CONNECTION POOLING
+#    We maintain our OWN Redis connection pool, separate from your app's
+#    Redis/Sidekiq. This prevents connection contention.
+#
+# 5. SAMPLING
+#    For high-traffic apps, you can sample errors (e.g., capture 50%)
+#    to reduce overhead further.
+#
+# DATA FLOW
+# =========
+#
+#   [Exception occurs]
+#          |
+#          v
+#   [Middleware catches it]
+#          |
+#          v
+#   [Scrub sensitive data]
+#          |
+#          v
+#   [Push to Redis buffer] <-- Async, non-blocking (Thread.new)
+#          |
+#          v
+#   [BackgroundPersister runs every 30s]
+#          |
+#          v
+#   [Batch insert to Database]
+#          |
+#          v
+#   [Dashboard displays data]
+#
+module Findbug
+  # Base error class for Findbug-specific exceptions
+  class Error < StandardError; end
+
+  class << self
+    # Access the configuration object
+    #
+    # @return [Configuration] the current configuration
+    #
+    # WHY A CLASS METHOD?
+    # -------------------
+    # We use `Findbug.config` instead of a global variable because:
+    # 1. It's lazily initialized (created on first access)
+    # 2. It's thread-safe (||= is atomic in MRI Ruby)
+    # 3. It's mockable in tests
+    # 4. It follows Ruby conventions (like Rails.config)
+    #
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Configure Findbug with a block
+    #
+    # @yield [Configuration] the configuration object
+    #
+    # @example
+    #   Findbug.configure do |config|
+    #     config.redis_url = "redis://localhost:6379/1"
+    #     config.sample_rate = 0.5
+    #
+    #     config.alerts do |alerts|
+    #       alerts.slack enabled: true, webhook_url: ENV["SLACK_WEBHOOK"]
+    #     end
+    #   end
+    #
+    def configure
+      yield(config) if block_given?
+      config.validate!
+      config
+    end
+
+    # Reset configuration to defaults (useful for testing)
+    #
+    # WHY EXPOSE THIS?
+    # ----------------
+    # In tests, you often want to reset state between examples.
+    # This makes Findbug test-friendly.
+    #
+    def reset!
+      @config = nil
+      @redis_pool = nil
+      @logger = nil
+    end
+
+    # Get the logger instance
+    #
+    # Falls back to Rails.logger, then to a null logger
+    #
+    def logger
+      @logger ||= config.logger || (defined?(Rails) && Rails.logger) || Logger.new(IO::NULL)
+    end
+
+    # Set a custom logger
+    def logger=(new_logger)
+      @logger = new_logger
+    end
+
+    # Check if Findbug is enabled
+    #
+    # This is a convenience method used throughout the codebase.
+    # It checks both the enabled flag AND validates we're properly configured.
+    #
+    def enabled?
+      config.enabled && config.redis_url.present?
+    end
+
+    # Capture an exception manually
+    #
+    # @param exception [Exception] the exception to capture
+    # @param context [Hash] additional context to attach
+    #
+    # @example
+    #   begin
+    #     risky_operation
+    #   rescue => e
+    #     Findbug.capture_exception(e, user_id: current_user.id)
+    #     raise # re-raise to let Rails handle it
+    #   end
+    #
+    # WHY A MANUAL CAPTURE METHOD?
+    # ----------------------------
+    # Sometimes you want to capture an exception without crashing.
+    # For example, in a rescue block where you handle the error
+    # gracefully but still want to track it.
+    #
+    def capture_exception(exception, context = {})
+      return unless enabled?
+      return unless config.should_capture_exception?(exception)
+
+      Capture::ExceptionHandler.capture(exception, context)
+    rescue StandardError => e
+      # CRITICAL: Never let Findbug crash your app
+      logger.error("[Findbug] Failed to capture exception: #{e.message}")
+    end
+
+    # Capture a message (non-exception event)
+    #
+    # @param message [String] the message to capture
+    # @param level [Symbol] severity level (:info, :warning, :error)
+    # @param context [Hash] additional context
+    #
+    # @example
+    #   Findbug.capture_message("User exceeded rate limit", :warning, user_id: 123)
+    #
+    def capture_message(message, level = :info, context = {})
+      return unless enabled?
+
+      Capture::MessageHandler.capture(message, level, context)
+    rescue StandardError => e
+      logger.error("[Findbug] Failed to capture message: #{e.message}")
+    end
+
+    # Wrap a block with performance tracking
+    #
+    # @param name [String] name for this operation
+    # @yield the block to track
+    #
+    # @example
+    #   Findbug.track_performance("external_api_call") do
+    #     ExternalAPI.fetch_data
+    #   end
+    #
+    def track_performance(name, &block)
+      return yield unless enabled? && config.performance_enabled
+
+      Performance::Transaction.track(name, &block)
+    rescue StandardError => e
+      logger.error("[Findbug] Performance tracking failed: #{e.message}")
+      yield # Still execute the block even if tracking fails
+    end
+  end
+end
+
+# Load core library modules (these stay in lib/ as they're not Rails-autoloadable)
+require_relative "findbug/storage/connection_pool"
+require_relative "findbug/storage/circuit_breaker"
+require_relative "findbug/storage/redis_buffer"
+require_relative "findbug/processing/data_scrubber"
+require_relative "findbug/capture/context"
+require_relative "findbug/capture/exception_handler"
+require_relative "findbug/capture/message_handler"
+require_relative "findbug/capture/middleware"
+
+# Load the Railtie if Rails is available
+# This auto-configures Findbug when Rails boots
+require_relative "findbug/railtie" if defined?(Rails::Railtie)

data/lib/generators/findbug/install_generator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Findbug
+  module Generators
+    # InstallGenerator sets up Findbug in a Rails application.
+    #
+    # Usage:
+    #   rails generate findbug:install
+    #
+    # This will:
+    #   1. Create the initializer (config/initializers/findbug.rb)
+    #   2. Create database migrations
+    #   3. Display next steps
+    #
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install Findbug: creates initializer and migrations"
+
+      class_option :skip_migrations,
+                   type: :boolean,
+                   default: false,
+                   desc: "Skip creating migrations"
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/findbug.rb"
+        say_status :create, "config/initializers/findbug.rb", :green
+      end
+
+      def create_migrations
+        return if options[:skip_migrations]
+
+        migration_template(
+          "create_findbug_error_events.rb",
+          "db/migrate/create_findbug_error_events.rb"
+        )
+
+        migration_template(
+          "create_findbug_performance_events.rb",
+          "db/migrate/create_findbug_performance_events.rb"
+        )
+
+        say_status :create, "db/migrate/create_findbug_error_events.rb", :green
+        say_status :create, "db/migrate/create_findbug_performance_events.rb", :green
+      end
+
+      def display_post_install
+        readme "POST_INSTALL" if behavior == :invoke
+      end
+
+      private
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/findbug/templates/POST_INSTALL

@@ -0,0 +1,41 @@
+
+===============================================================================
+  Findbug has been installed successfully!
+===============================================================================
+
+Next steps:
+
+1. Run the migrations:
+
+     rails db:migrate
+
+2. Configure Redis URL (if different from default):
+
+     # Add to your environment variables or .env file:
+     FINDBUG_REDIS_URL=redis://localhost:6379/1
+
+     # Or set directly in config/initializers/findbug.rb:
+     config.redis_url = "redis://localhost:6379/1"
+
+3. Configure dashboard authentication (required):
+
+     # Add to your environment variables or .env file:
+     FINDBUG_USERNAME=admin
+     FINDBUG_PASSWORD=your-secure-password
+
+5. Access the dashboard:
+
+     http://localhost:3000/findbug
+
+6. (Optional) Configure alerts in config/initializers/findbug.rb:
+
+     config.alerts do |alerts|
+       alerts.slack(
+         enabled: true,
+         webhook_url: ENV["SLACK_WEBHOOK_URL"]
+       )
+     end
+
+For more information, see: https://github.com/ITSSOUMIT/findbug
+
+===============================================================================

data/lib/generators/findbug/templates/create_findbug_error_events.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+class CreateFindbugErrorEvents < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :findbug_error_events do |t|
+      # Error identification
+      t.string :fingerprint, null: false
+      t.string :exception_class, null: false
+      t.text :message
+      t.text :backtrace
+
+      # Context (stored as JSON for flexibility)
+      t.jsonb :context, default: {}
+      t.jsonb :request_data, default: {}
+
+      # Metadata
+      t.string :environment
+      t.string :release_version
+      t.string :severity, default: "error"
+      t.string :source
+      t.boolean :handled, default: false
+
+      # Aggregation
+      t.integer :occurrence_count, default: 1
+      t.datetime :first_seen_at
+      t.datetime :last_seen_at
+
+      # Status tracking
+      t.string :status, default: "unresolved"
+
+      t.timestamps
+    end
+
+    # Indexes for common queries
+    add_index :findbug_error_events, :fingerprint
+    add_index :findbug_error_events, :exception_class
+    add_index :findbug_error_events, :status
+    add_index :findbug_error_events, :severity
+    add_index :findbug_error_events, :last_seen_at
+    add_index :findbug_error_events, :created_at
+    add_index :findbug_error_events, [:status, :last_seen_at]
+    add_index :findbug_error_events, [:exception_class, :created_at]
+  end
+end

data/lib/generators/findbug/templates/create_findbug_performance_events.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+class CreateFindbugPerformanceEvents < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :findbug_performance_events do |t|
+      # Transaction identification
+      t.string :transaction_name, null: false
+      t.string :transaction_type, default: "request"
+
+      # Request info
+      t.string :request_method
+      t.string :request_path
+      t.string :format
+      t.integer :status
+
+      # Timing (all in milliseconds)
+      t.float :duration_ms, null: false
+      t.float :db_time_ms, default: 0
+      t.float :view_time_ms, default: 0
+
+      # Query tracking
+      t.integer :query_count, default: 0
+      t.jsonb :slow_queries, default: []
+      t.jsonb :n_plus_one_queries, default: []
+      t.boolean :has_n_plus_one, default: false
+      t.integer :view_count, default: 0
+
+      # Context
+      t.jsonb :context, default: {}
+
+      # Metadata
+      t.string :environment
+      t.string :release_version
+      t.datetime :captured_at
+
+      t.timestamps
+    end
+
+    # Indexes for common queries (using short names to stay under 63 char limit)
+    add_index :findbug_performance_events, :transaction_name, name: "idx_fb_perf_txn_name"
+    add_index :findbug_performance_events, :transaction_type, name: "idx_fb_perf_txn_type"
+    add_index :findbug_performance_events, :captured_at, name: "idx_fb_perf_captured_at"
+    add_index :findbug_performance_events, :duration_ms, name: "idx_fb_perf_duration"
+    add_index :findbug_performance_events, :has_n_plus_one, name: "idx_fb_perf_n_plus_one"
+    add_index :findbug_performance_events, [:transaction_name, :captured_at], name: "idx_fb_perf_txn_captured"
+  end
+end