findbug 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 494c404f3c7c5304cc166a253ccf04757b9b2ab2728c280931f9b1643ce5c5aa
+  data.tar.gz: 9e21ab5ccfd0c92df80d0517176201a46dc4854e238cc70a2ada04461ff647b0
+SHA512:
+  metadata.gz: 9bedec8cfb4d78ab1e11205353b883e0fe035e30692d2485208db7382a98e5d97398df436a5acf19e0329eb9d60db4bdbdf69605281c7ba714bcabdaef2c5347
+  data.tar.gz: c3d2af6ee0473bd1ac01330b912b892ac23a125c12e11bfb0f9b138a9bc411d1eb6bf722f627d6397c2d20ce308e00d1c18a1e5c8cefed76ca86bec8da3d9ff5

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Soumit Das
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,375 @@
+# Findbug
+
+[![Gem Version](https://badge.fury.io/rb/findbug.svg)](https://badge.fury.io/rb/findbug)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub](https://img.shields.io/github/stars/ITSSOUMIT/findbug?style=social)](https://github.com/ITSSOUMIT/findbug)
+
+**Self-hosted error tracking and performance monitoring for Rails applications.**
+
+Findbug provides Sentry-like functionality with all data stored on your own infrastructure using Redis and your database. Zero external dependencies, full data ownership.
+
+## Features
+
+- **Error Tracking** - Capture exceptions with full context, stack traces, and request data
+- **Performance Monitoring** - Track request timing, SQL queries, and automatic N+1 detection
+- **Self-Hosted** - All data stays on your infrastructure (Redis + PostgreSQL/MySQL)
+- **Zero Performance Impact** - Async writes via Redis buffer, never blocks your requests
+- **Built-in Dashboard** - Beautiful web UI for viewing errors and performance metrics
+- **Multi-channel Alerts** - Email, Slack, Discord, and custom webhooks
+- **Works Out of the Box** - Built-in background persister, no job scheduler required
+- **Rails 7+ Native** - Designed for modern Rails applications
+
+## Why Findbug?
+
+| Feature | Sentry/Bugsnag | Findbug |
+|---------|----------------|---------|
+| Data Location | Third-party servers | Your infrastructure |
+| Monthly Cost | $26+ per seat | Free |
+| Privacy/Compliance | Requires DPA | Full control |
+| Network Dependency | Required | None |
+| Setup Complexity | API keys, SDKs | One gem, one command |
+
+## Requirements
+
+- Ruby 3.1+
+- Rails 7.0+
+- Redis 4.0+
+- PostgreSQL or MySQL
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'findbug'
+```
+
+Run the installer:
+
+```bash
+bundle install
+rails generate findbug:install
+rails db:migrate
+```
+
+## Quick Start
+
+### 1. Configure Redis (Optional)
+
+Findbug uses Redis as a high-speed buffer. By default, it connects to `redis://localhost:6379/1`.
+
+To use a different Redis URL, set the environment variable:
+
+```bash
+export FINDBUG_REDIS_URL=redis://localhost:6379/1
+```
+
+Or configure in `config/initializers/findbug.rb`:
+
+```ruby
+config.redis_url = ENV.fetch("FINDBUG_REDIS_URL", "redis://localhost:6379/1")
+```
+
+### 2. Enable the Dashboard
+
+Set credentials via environment variables:
+
+```bash
+export FINDBUG_USERNAME=admin
+export FINDBUG_PASSWORD=your-secure-password
+```
+
+Access the dashboard at: `http://localhost:3000/findbug`
+
+### 3. That's It!
+
+Findbug automatically:
+- Captures unhandled exceptions
+- Monitors request performance
+- Persists data to your database (via built-in background thread)
+- No additional job scheduler required
+
+## Configuration
+
+All configuration options in `config/initializers/findbug.rb`:
+
+```ruby
+Findbug.configure do |config|
+  # ===================
+  # Core Settings
+  # ===================
+  config.enabled = !Rails.env.test?
+  config.redis_url = ENV.fetch("FINDBUG_REDIS_URL", "redis://localhost:6379/1")
+  config.redis_pool_size = 5
+
+  # ===================
+  # Error Capture
+  # ===================
+  config.sample_rate = 1.0  # Capture 100% of errors
+  config.ignored_exceptions = [
+    ActiveRecord::RecordNotFound,
+    ActionController::RoutingError
+  ]
+  config.ignored_paths = [/^\/health/, /^\/assets/]
+
+  # ===================
+  # Performance Monitoring
+  # ===================
+  config.performance_enabled = true
+  config.performance_sample_rate = 0.1  # Sample 10% of requests
+  config.slow_request_threshold_ms = 0
+  config.slow_query_threshold_ms = 100
+
+  # ===================
+  # Data Security
+  # ===================
+  config.scrub_fields = %w[password api_key credit_card ssn token secret]
+  config.scrub_headers = true
+
+  # ===================
+  # Storage & Retention
+  # ===================
+  config.retention_days = 30
+  config.max_buffer_size = 10_000
+
+  # ===================
+  # Dashboard
+  # ===================
+  config.web_username = ENV["FINDBUG_USERNAME"]
+  config.web_password = ENV["FINDBUG_PASSWORD"]
+  config.web_path = "/findbug"
+
+  # ===================
+  # Alerts (Optional)
+  # ===================
+  config.alerts do |alerts|
+    alerts.throttle_period = 5.minutes
+
+    # Slack
+    # alerts.slack(
+    #   enabled: true,
+    #   webhook_url: ENV["SLACK_WEBHOOK_URL"],
+    #   channel: "#errors"
+    # )
+
+    # Email
+    # alerts.email(
+    #   enabled: true,
+    #   recipients: ["team@example.com"]
+    # )
+
+    # Discord
+    # alerts.discord(
+    #   enabled: true,
+    #   webhook_url: ENV["DISCORD_WEBHOOK_URL"]
+    # )
+
+    # Custom Webhook
+    # alerts.webhook(
+    #   enabled: true,
+    #   url: "https://your-service.com/webhook",
+    #   headers: { "Authorization" => "Bearer token" }
+    # )
+  end
+end
+```
+
+## Usage
+
+### Automatic Error Capture
+
+Findbug automatically captures:
+- Unhandled exceptions in controllers
+- Errors reported via `Rails.error.handle` / `Rails.error.report`
+- Any exception that bubbles up through the middleware stack
+
+### Manual Error Capture
+
+```ruby
+# Capture an exception with context
+begin
+  risky_operation
+rescue => e
+  Findbug.capture_exception(e, user_id: current_user.id)
+  # Handle gracefully...
+end
+
+# Capture a message (non-exception event)
+Findbug.capture_message("Rate limit exceeded", :warning, user_id: 123)
+```
+
+### Adding Context
+
+In your `ApplicationController`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :set_findbug_context
+
+  private
+
+  def set_findbug_context
+    findbug_set_user(current_user)
+    findbug_set_context(
+      plan: current_user&.plan,
+      organization_id: current_org&.id
+    )
+  end
+end
+```
+
+### Breadcrumbs
+
+Track events leading up to an error:
+
+```ruby
+findbug_breadcrumb("User clicked checkout", category: "ui")
+findbug_breadcrumb("Payment API called", category: "http", data: { amount: 99.99 })
+```
+
+### Performance Tracking
+
+Automatic tracking includes:
+- HTTP request duration
+- SQL query count and timing
+- N+1 query detection
+- View rendering time
+
+Manual tracking for custom operations:
+
+```ruby
+Findbug.track_performance("external_api_call") do
+  ExternalAPI.fetch_data
+end
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Your Rails App                          │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Request ──► Middleware ──► Exception? ──► Redis Buffer        │
+│                                               (async, ~1ms)     │
+│                                                    │            │
+│  Request ──► Instrumentation ──► Perf Data ──► Redis Buffer    │
+│                                               (async, ~1ms)     │
+│                                                    │            │
+│                                                    ▼            │
+│                                         ┌──────────────────┐   │
+│                                         │ BackgroundThread │   │
+│                                         │   (every 30s)    │   │
+│                                         └────────┬─────────┘   │
+│                                                  │              │
+│                                                  ▼              │
+│  Dashboard ◄──────────────────── Database (PostgreSQL/MySQL)   │
+│  (/findbug)                                                     │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Performance Guarantees:**
+- Error capture: ~1-2ms (async Redis write)
+- Never blocks your HTTP requests
+- Circuit breaker auto-disables if Redis is unavailable
+- Dedicated connection pool (won't affect your app's Redis usage)
+
+## Rake Tasks
+
+```bash
+# Show configuration and system status
+rails findbug:status
+
+# Test error capture
+rails findbug:test
+
+# Manually flush Redis buffer to database
+rails findbug:flush
+
+# Run retention cleanup
+rails findbug:cleanup
+
+# Clear Redis buffers (use with caution)
+rails findbug:clear_buffers
+
+# Show database statistics
+rails findbug:db:stats
+```
+
+## Advanced: Using ActiveJob Instead of Built-in Thread
+
+By default, Findbug uses a built-in background thread for persistence. If you prefer to use ActiveJob with your own job backend:
+
+```ruby
+# config/initializers/findbug.rb
+config.auto_persist = false  # Disable built-in thread
+```
+
+Then schedule the jobs with your preferred scheduler:
+
+```ruby
+# With any scheduler (Sidekiq, GoodJob, Solid Queue, etc.)
+Findbug::PersistJob.perform_later   # Run every 30 seconds
+Findbug::CleanupJob.perform_later   # Run daily
+```
+
+## API Reference
+
+### Error Capture
+
+```ruby
+Findbug.capture_exception(exception, context = {})
+Findbug.capture_message(message, level = :info, context = {})
+```
+
+### Performance Tracking
+
+```ruby
+Findbug.track_performance(name) { ... }
+```
+
+### Controller Helpers
+
+```ruby
+findbug_set_user(user)
+findbug_set_context(hash)
+findbug_breadcrumb(message, category:, data: {})
+```
+
+### Configuration
+
+```ruby
+Findbug.config           # Access configuration
+Findbug.enabled?         # Check if enabled
+Findbug.reset!           # Reset configuration (for testing)
+```
+
+## Development
+
+```bash
+git clone https://github.com/ITSSOUMIT/findbug.git
+cd findbug
+bin/setup
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ITSSOUMIT/findbug.
+
+If you encounter any bugs, please open an issue or send an email to hey@soumit.in.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes (`git commit -am 'Add my feature'`)
+4. Push to the branch (`git push origin feature/my-feature`)
+5. Create a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Built by [Soumit Das](https://github.com/ITSSOUMIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/app/controllers/findbug/application_controller.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Findbug
+  # ApplicationController is the base controller for all Findbug dashboard controllers.
+  #
+  # AUTHENTICATION
+  # ==============
+  #
+  # We use HTTP Basic Auth for simplicity (same as Sidekiq).
+  #
+  # Why Basic Auth?
+  # - Simple to set up (just username/password in config)
+  # - Works with any deployment (no OAuth setup needed)
+  # - Stateless (no session management)
+  # - Secure enough for internal tools (over HTTPS)
+  #
+  # If you need more sophisticated auth (SSO, OAuth, role-based):
+  # - Override `authenticate!` in your app
+  # - Or use a Rack middleware before the engine
+  #
+  class ApplicationController < ActionController::Base
+    # Protect from forgery with exception
+    protect_from_forgery with: :exception
+
+    # Authenticate before all actions
+    before_action :authenticate!
+    before_action :set_findbug_view_path
+
+    # Set layout
+    layout "findbug/application"
+
+    # Helper methods
+    helper_method :findbug_path
+
+    private
+
+    # HTTP Basic Authentication
+    #
+    # WHY BASIC AUTH?
+    # ---------------
+    # 1. Zero setup for users (no OAuth, no devise)
+    # 2. Works everywhere (curl, browser, CI)
+    # 3. Secure over HTTPS
+    # 4. Same pattern as Sidekiq (users know it)
+    #
+    def authenticate!
+      return true unless Findbug.config.web_enabled?
+
+      authenticate_or_request_with_http_basic("Findbug") do |username, password|
+        # Use secure comparison to prevent timing attacks
+        secure_compare(username, Findbug.config.web_username) &&
+          secure_compare(password, Findbug.config.web_password)
+      end
+    end
+
+    # Secure string comparison (constant-time)
+    #
+    # WHY CONSTANT-TIME?
+    # ------------------
+    # Normal string comparison stops at the first different character.
+    # An attacker could measure response times to guess characters one by one.
+    # Constant-time comparison always takes the same time regardless of input.
+    #
+    def secure_compare(a, b)
+      return false if a.nil? || b.nil?
+
+      ActiveSupport::SecurityUtils.secure_compare(a.to_s, b.to_s)
+    end
+
+    # Helper to get the engine's mount path
+    def findbug_path
+      Findbug.config.web_path
+    end
+
+    # Add the gem's view path so templates can be found
+    # This runs before each request to ensure the path is set
+    def set_findbug_view_path
+      return unless defined?(FINDBUG_GEM_ROOT)
+
+      views_path = File.join(FINDBUG_GEM_ROOT, "app", "views")
+      prepend_view_path(views_path) unless view_paths.include?(views_path)
+    end
+
+    # Handle ActiveRecord errors gracefully
+    rescue_from ActiveRecord::RecordNotFound do |e|
+      flash_error "Record not found"
+      redirect_to findbug.root_path
+    end
+
+    # Safe flash helpers that work with API-only Rails apps
+    def flash_success(message)
+      flash[:success] = message if flash_available?
+    end
+
+    def flash_error(message)
+      flash[:error] = message if flash_available?
+    end
+
+    def flash_available?
+      respond_to?(:flash) && flash.respond_to?(:[]=)
+    rescue NoMethodError
+      false
+    end
+  end
+end

data/app/controllers/findbug/dashboard_controller.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Findbug
+  # DashboardController handles the main dashboard view.
+  #
+  class DashboardController < ApplicationController
+    # GET /findbug
+    #
+    # Main dashboard with overview of errors and performance.
+    #
+    def index
+      @stats = calculate_stats
+      @recent_errors = Findbug::ErrorEvent.unresolved.recent.limit(10)
+      @slowest_endpoints = Findbug::PerformanceEvent.slowest_transactions(since: 24.hours.ago, limit: 5)
+      @error_trend = calculate_error_trend
+
+      render template: "findbug/dashboard/index", layout: "findbug/application"
+    end
+
+    # GET /findbug/health
+    #
+    # Health check endpoint for monitoring.
+    # Returns JSON with system status.
+    #
+    def health
+      status = {
+        status: "ok",
+        version: Findbug::VERSION,
+        redis: check_redis_health,
+        database: check_database_health,
+        buffer: Findbug::Storage::RedisBuffer.stats
+      }
+
+      render json: status
+    end
+
+    # GET /findbug/stats
+    #
+    # JSON stats endpoint for AJAX updates.
+    # Used by Turbo to refresh dashboard stats without full page reload.
+    #
+    def stats
+      render json: calculate_stats
+    end
+
+    private
+
+    def calculate_stats
+      now = Time.current
+      {
+        errors: {
+          total: Findbug::ErrorEvent.count,
+          unresolved: Findbug::ErrorEvent.unresolved.count,
+          last_24h: Findbug::ErrorEvent.where("created_at >= ?", 24.hours.ago).count,
+          last_7d: Findbug::ErrorEvent.where("created_at >= ?", 7.days.ago).count
+        },
+        performance: {
+          total: Findbug::PerformanceEvent.count,
+          last_24h: Findbug::PerformanceEvent.where("captured_at >= ?", 24.hours.ago).count,
+          avg_duration: Findbug::PerformanceEvent.where("captured_at >= ?", 24.hours.ago)
+                                        .average(:duration_ms)&.round(2) || 0,
+          n_plus_one_count: Findbug::PerformanceEvent.with_n_plus_one
+                                            .where("captured_at >= ?", 24.hours.ago)
+                                            .count
+        },
+        buffer: Findbug::Storage::RedisBuffer.stats,
+        timestamp: now.iso8601
+      }
+    end
+
+    def calculate_error_trend
+      # Get hourly error counts for the last 24 hours
+      Findbug::ErrorEvent.where("last_seen_at >= ?", 24.hours.ago)
+                .group_by_hour(:last_seen_at)
+                .count
+    rescue NoMethodError
+      # groupdate gem not installed, return simple count
+      {}
+    end
+
+    def check_redis_health
+      Findbug::Storage::ConnectionPool.healthy? ? "ok" : "error"
+    rescue StandardError
+      "error"
+    end
+
+    def check_database_health
+      Findbug::ErrorEvent.connection.active? ? "ok" : "error"
+    rescue StandardError
+      "error"
+    end
+  end
+end