lapsoss 0.1.0 → 0.3.0

data/README.md

@@ -1,855 +1,275 @@
-# Lapsoss 🧬
+# Lapsoss - Vendor-Neutral Error Reporting for Rails
 
-**Adaptive Trait Selection for Error Tracking**
+## The Problem We All Face
 
-Lapsoss is a vendor-neutral error tracking library for Ruby that applies the principle of "Adaptive Trait Selection" - intelligently selecting the best features from each error tracking ecosystem to create a superior, unified solution.
+You're 6 months into production with Bugsnag. The CFO says "costs are too high, switch to Sentry."
 
-## Philosophy
+The migration estimate? 3 months. Why? Because your entire codebase is littered with:
+- `Bugsnag.notify(exception)`
+- `Bugsnag.leave_breadcrumb("User clicked checkout")`
+- Bugsnag-specific configuration
+- Custom Bugsnag metadata patterns
 
-Lapsoss is built on the principle of absolute vendor neutrality and control. Unlike traditional error tracking libraries that often bundle proprietary SDKs, Lapsoss provides a pure Ruby implementation for error reporting. This ensures:
+**This is vendor lock-in through API pollution.**
 
-- **No External SDK Dependencies**: Lapsoss handles payload construction and transport directly, eliminating the need for any third-party error tracking gems.
-- **Zero Monkey-Patching**: Your application's core behavior remains untouched.
-- **Complete Control**: You dictate how errors are processed and sent, without hidden telemetry or unwanted features.
-- **True Vendor Agnosticism**: Switch or combine error tracking services seamlessly, without changing your application's code.
-
-## Rails-First Architecture
-
-Lapsoss is designed **primarily for Rails applications** and modern Ruby projects. This architectural choice provides clear benefits:
-
-### Why ActiveSupport?
-
-Lapsoss depends on ActiveSupport (Rails 7.2+) as a deliberate design decision:
-
-- **Rails Integration**: Seamless integration with Rails' parameter filtering, configuration patterns, and error reporting API
-- **Essential Utilities**: ActiveSupport provides utilities we need anyway: `concurrent-ruby`, `zeitwerk`, inflection, configuration handling
-- **No Namespace Pollution**: Unlike vendor SDKs that bring Redis, Elasticsearch, and other external namespaces, ActiveSupport provides clean Ruby utilities
-- **Your Choice**: Use Lapsoss with ActiveSupport, or use official vendor SDKs that monkey-patch your entire application
-
-### The Real Bloat Problem
-
-The issue isn't dependency count - it's **namespace pollution** and **monkey-patching**:
-
-- **Vendor SDKs**: Force Redis, Elasticsearch, proprietary gems, and monkey-patch core Ruby classes
-- **Lapsoss + ActiveSupport**: Clean utilities that enhance Ruby without breaking your application's behavior
-
-### Ruby Implementation Support
-
-Lapsoss is built and tested exclusively for **CRuby (MRI) 3.2+**. Other Ruby implementations (JRuby, TruffleRuby) are not supported. This focused approach allows us to:
-
-- Optimize for the most common Ruby implementation
-- Avoid complexity of cross-implementation compatibility
-- Provide reliable backtrace processing and code context extraction
-
-### Rails Version Support
-
-Lapsoss targets **Rails 7.2+** applications. If you're running an older Rails version, upgrade first. We follow Rails' release support policy and focus on modern Rails applications.
-
-### What Lapsoss Is (and Isn't)
-
-**Lapsoss is not a full replacement for vendor SDKs.** It focuses on core error tracking functionality, providing a Rails-optimized alternative for teams that:
-
-- Want clean, vendor-neutral error reporting without external namespace pollution
-- Need to use multiple error tracking services simultaneously  
-- Are tired of vendor SDKs that monkey-patch core Ruby classes
-- Want to avoid the complexity of legacy support and premium features you don't use
-
-**What's included:**
-- ✅ Exception and error message capture
-- ✅ Contextual data (user, tags, extra data)
-- ✅ Breadcrumbs and error grouping
-- ✅ Deploy markers and release tracking
-- ✅ Basic health checks/heartbeats
-- ✅ **Custom fingerprinting for intelligent error grouping**
-- ✅ **Automatic data scrubbing with Rails parameter filtering**
-- ✅ **Transport reliability with retry logic and client-side rate limiting**
-- ✅ **Configuration validation for all adapter settings**
-- ✅ **Advanced backtrace processing with code context extraction**
-- ✅ **Intelligent frame filtering and normalization**
-- ✅ **Performance-optimized file caching for backtrace processing**
-
-**What's NOT included:**
-- ❌ Application Performance Monitoring (APM)
-- ❌ Distributed tracing
-- ❌ Host metrics and system monitoring
-- ❌ Advanced profiling
-- ❌ Database query analysis
-
-Most vendor SDKs contain significant boilerplate to support legacy Ruby versions, deprecated features, and premium functionality that requires additional subscriptions. Lapsoss strips away this complexity, focusing on what most applications actually need: reliable error tracking.
-
-> 📖 **Want the full story?** Read [STORY.md](STORY.md) for detailed research on SDK bloat, including actual gem sizes and feature creep analysis across 25+ releases of major error tracking libraries.
-
-## Core Principles (COSS-Compliant)
-
-Lapsoss adheres strictly to the [Contriboss (COSS) standard](https://www.contriboss.com), ensuring software neutrality and freedom from vendor lock-in.
-
-- 🔓 **Absolute Vendor Neutrality**: Lapsoss provides its own pure Ruby implementations for error reporting, eliminating the need for any external vendor SDKs.
-- 🔌 **Pluggable Adapters**: Configure and use one or multiple built-in or custom adapters simultaneously.
-- 🚀 **Rails 7.2+ Native Integration**: Seamlessly integrates with Rails' native error reporting API, without any monkey-patching.
-- 🧬 **Adaptive Trait Selection**: I've carefully selected and implemented the most valuable error reporting features directly within Lapsoss, providing a unified, best-of-breed solution.
-
-## Installation
+## The Solution: Write Once, Deploy Anywhere
 
 ```ruby
-gem 'lapsoss'
-```
-
-## Quick Start
+# Your code never changes:
+Lapsoss.capture_exception(e)
 
-Lapsoss currently provides 4 built-in adapters:
-- **Sentry** - Full error tracking support with pure Ruby implementation
-- **AppSignal** - Error tracking, deploy markers, and check-ins support (messages limited to :error, :fatal, :critical levels)
-- **Rollbar** - Complete error tracking with grouping and person tracking
-- **Insight Hub** (formerly Bugsnag) - Error tracking with breadcrumbs and session support
+# Switch vendors in config, not code:
+Lapsoss.configure do |config|
+  # Monday: Using Bugsnag
+  config.use_bugsnag(api_key: ENV['BUGSNAG_KEY'])
 
-All adapters are pure Ruby implementations with no external SDK dependencies or monkey-patching. Additional adapters can be easily added by the community or vendors.
+  # Tuesday: Add Sentry for comparison
+  config.use_sentry(dsn: ENV['SENTRY_DSN'])
 
-### Single Adapter (Simple Mode)
-```ruby
-# config/initializers/lapsoss.rb
-Lapsoss.configure do |config|
-  # Configure the built-in Sentry adapter
-  config.use_sentry(dsn: ENV["SENTRY_DSN"])
+  # Wednesday: Drop Bugsnag, keep Sentry
+  # Just remove the line. Zero code changes.
 end
 ```
 
-### Multi-Adapter (Advanced Mode)
-```ruby
-# config/initializers/lapsoss.rb
-Lapsoss.configure do |config|
-  # Run multiple built-in adapters simultaneously!
-  config.use_sentry(name: :sentry_us, dsn: ENV['SENTRY_US_DSN'])
-  config.use_sentry(name: :sentry_eu, dsn: ENV['SENTRY_EU_DSN'])
-  config.use_appsignal(name: :appsignal, api_key: ENV['APPSIGNAL_API_KEY'])
-  config.use_rollbar(name: :rollbar, access_token: ENV['ROLLBAR_ACCESS_TOKEN'])
-  config.use_insight_hub(name: :insight_hub, api_key: ENV['INSIGHT_HUB_API_KEY'])
-  config.use_logger(name: :local_backup) # Example: log errors to a local file
-end
+## Installation
 
-# For Rails applications, errors are automatically captured via the Rails error reporting API.
-# For other Ruby applications, use Lapsoss.capture_exception or Lapsoss.capture_message.
+```ruby
+gem 'lapsoss'
 ```
 
 ## Usage
 
-### Core API
-
-Lapsoss provides a simple, intuitive API for error tracking:
-
 ```ruby
 # Capture exceptions
-Lapsoss.capture_exception(exception, **context)
+Lapsoss.capture_exception(e)
 
 # Capture messages
-Lapsoss.capture_message(message, level: :info, **context)
+Lapsoss.capture_message("Payment processed", level: :info)
 
-# Add breadcrumbs for debugging context
-Lapsoss.add_breadcrumb(message, type: :default, **metadata)
-
-# Work with scoped context
-Lapsoss.with_scope(context = {}, &block)
-Lapsoss.current_scope
-```
-
-### Rails Integration
-
-For Rails applications, errors are automatically captured:
-
-```ruby
-# config/initializers/lapsoss.rb
-Lapsoss.configure do |config|
-  config.use_sentry(dsn: ENV["SENTRY_DSN"])
+# Add context
+Lapsoss.with_scope(user_id: current_user.id) do
+  process_payment
 end
 
-# That's it! All unhandled exceptions are automatically captured
-# No need to modify your controllers or models
+# Add breadcrumbs
+Lapsoss.add_breadcrumb("User clicked checkout", type: :navigation)
 ```
 
-### Manual Error Capture
+That's it. No 500-line examples needed.
+
+## Built for Rails, Not Around It
 
-For non-Rails applications or custom error handling:
+Lapsoss integrates with Rails' native error reporting API introduced in Rails 7. No monkey-patching, no middleware gymnastics:
 
 ```ruby
-# Basic exception capture
-begin
+# It just works with Rails.error:
+Rails.error.handle(context: {user_id: current_user.id}) do
   risky_operation
-rescue => e
-  Lapsoss.capture_exception(e)
-end
-
-# With additional context
-begin
-  process_payment(user, amount)
-rescue PaymentError => e
-  Lapsoss.capture_exception(e, 
-    user: { id: user.id, email: user.email },
-    tags: { payment_method: "credit_card", amount: amount },
-    extra: { order_id: order.id, retry_count: 3 }
-  )
 end
+# Automatically captured by whatever service you configured
 ```
 
-### Message Logging
-
-For important events or custom alerts:
+## Zero-Downtime Vendor Migration
 
 ```ruby
-# Simple message
-Lapsoss.capture_message("Payment processing started", level: :info)
-
-# With context
-Lapsoss.capture_message("High CPU usage detected", 
-  level: :warning,
-  tags: { server: "web-01", cpu_usage: "85%" },
-  extra: { pid: Process.pid, memory_usage: "2.1GB" }
-)
-```
+# Step 1: Add Lapsoss alongside your current setup
+gem 'lapsoss'
+gem 'bugsnag' # Keep your existing gem for now
 
-### Breadcrumbs for Debugging
+# Step 2: Configure dual reporting
+Lapsoss.configure do |config|
+  config.use_bugsnag(api_key: ENV['BUGSNAG_KEY'])
+  config.use_sentry(dsn: ENV['SENTRY_DSN'])
+end
 
-Track user actions and system events leading up to errors:
+# Step 3: Gradually replace Bugsnag calls
+# Old: Bugsnag.notify(e)
+# New: Lapsoss.capture_exception(e)
 
-```ruby
-# User actions
-Lapsoss.add_breadcrumb("User logged in", 
-  type: :user, 
-  user_id: user.id, 
-  ip: request.remote_ip
-)
-
-# System events
-Lapsoss.add_breadcrumb("Database connection established", 
-  type: :system, 
-  host: "db-primary", 
-  latency: "45ms"
-)
-
-# Navigation
-Lapsoss.add_breadcrumb("User visited checkout", 
-  type: :navigation, 
-  url: "/checkout", 
-  referrer: "/cart"
-)
-
-# When an error occurs, all breadcrumbs are included automatically
-begin
-  complete_checkout
-rescue => e
-  Lapsoss.capture_exception(e) # Includes all breadcrumbs above
-end
+# Step 4: Remove bugsnag gem when ready
+# Your app keeps running, now on Sentry
 ```
 
-### Scoped Context
+## Why Not Just Use Vendor SDKs?
 
-Use scoped context to apply data to multiple operations:
+**Vendor SDKs monkey-patch your application:**
+- Sentry patches Net::HTTP, Redis, and 20+ other gems
+- Each vendor races to patch the same methods
+- Multiple SDKs = multiple layers of patches
+- Your app behavior changes based on load order
 
-```ruby
-# Request-scoped context
-Lapsoss.with_scope(
-  user: { id: current_user.id, email: current_user.email },
-  tags: { request_id: request.id, controller: "checkout" }
-) do
-  
-  # Any errors in this block will include the scope context
-  process_payment
-  update_inventory
-  send_confirmation_email
-  
-end
-
-# Background job context
-Lapsoss.with_scope(
-  tags: { job: "invoice_generator", queue: "high_priority" },
-  extra: { batch_size: invoices.count }
-) do
-  
-  invoices.each do |invoice|
-    Lapsoss.add_breadcrumb("Processing invoice #{invoice.id}")
-    generate_invoice(invoice)
-  end
-  
-end
-```
+**Lapsoss doesn't patch anything:**
+- Pure Ruby implementation
+- Uses Rails' error API
+- Your app behavior remains unchanged
+- No competing instrumentation
 
-### Real-World Examples
+## Real-World Use Cases
 
-#### E-commerce Checkout Flow
+### GDPR Compliance
 ```ruby
-class CheckoutController < ApplicationController
-  def create
-    Lapsoss.with_scope(
-      user: { id: current_user.id, email: current_user.email },
-      tags: { controller: "checkout", action: "create" },
-      extra: { cart_total: cart.total, item_count: cart.items.count }
-    ) do
-      
-      Lapsoss.add_breadcrumb("Checkout initiated", type: :user)
-      
-      begin
-        payment = process_payment(cart.total)
-        Lapsoss.add_breadcrumb("Payment processed", type: :system, 
-          payment_id: payment.id, method: payment.method)
-        
-        order = create_order(cart, payment)
-        Lapsoss.add_breadcrumb("Order created", type: :system, order_id: order.id)
-        
-        redirect_to order_path(order)
-        
-      rescue PaymentError => e
-        Lapsoss.capture_exception(e, 
-          tags: { error_type: "payment_failure" },
-          extra: { payment_method: params[:payment_method] }
-        )
-        redirect_to checkout_path, alert: "Payment failed"
-        
-      rescue InventoryError => e
-        Lapsoss.capture_exception(e, 
-          tags: { error_type: "inventory_failure" },
-          extra: { requested_items: cart.items.pluck(:id) }
-        )
-        redirect_to cart_path, alert: "Item no longer available"
-      end
-      
-    end
-  end
-end
+# Route EU data to EU servers, US data to US servers
+config.use_sentry(name: :us, dsn: ENV['US_DSN'])
+config.use_sentry(name: :eu, dsn: ENV['EU_DSN'])
 ```
 
-#### Background Job Error Handling
+### A/B Testing Error Services
 ```ruby
-class InvoiceGeneratorJob < ApplicationJob
-  def perform(batch_id)
-    Lapsoss.with_scope(
-      tags: { job: "invoice_generator", batch_id: batch_id },
-      extra: { queue: queue_name, priority: priority }
-    ) do
-      
-      invoices = Invoice.where(batch_id: batch_id)
-      
-      invoices.each_with_index do |invoice, index|
-        Lapsoss.add_breadcrumb("Processing invoice #{invoice.id}", 
-          type: :system, 
-          progress: "#{index + 1}/#{invoices.count}"
-        )
-        
-        begin
-          generate_pdf(invoice)
-          send_email(invoice)
-          invoice.update!(status: :sent)
-          
-        rescue => e
-          Lapsoss.capture_exception(e, 
-            tags: { error_type: "invoice_generation_failure" },
-            extra: { invoice_id: invoice.id, customer_id: invoice.customer_id }
-          )
-          
-          invoice.update!(status: :failed)
-        end
-      end
-      
-    end
-  end
-end
+# Run both services, compare effectiveness
+config.use_rollbar(name: :current, access_token: ENV['ROLLBAR_TOKEN'])
+config.use_sentry(name: :candidate, dsn: ENV['SENTRY_DSN'])
 ```
 
-#### API Error Tracking
+### High Availability
 ```ruby
-class ApiController < ApplicationController
-  around_action :track_api_errors
-
-  private
-  
-  def track_api_errors
-    Lapsoss.with_scope(
-      tags: { 
-        api_version: request.headers["API-Version"],
-        endpoint: "#{params[:controller]}##{params[:action]}" 
-      },
-      extra: { 
-        user_agent: request.user_agent,
-        ip_address: request.remote_ip 
-      }
-    ) do
-      
-      Lapsoss.add_breadcrumb("API request started", 
-        type: :http, 
-        url: request.path, 
-        method: request.method
-      )
-      
-      begin
-        yield
-        
-      rescue RateLimitError => e
-        Lapsoss.capture_exception(e, 
-          tags: { error_type: "rate_limit_exceeded" },
-          extra: { limit: e.limit, reset_time: e.reset_time }
-        )
-        render json: { error: "Rate limit exceeded" }, status: 429
-        
-      rescue AuthenticationError => e
-        Lapsoss.capture_exception(e, 
-          tags: { error_type: "authentication_failure" },
-          extra: { auth_method: request.headers["Authorization"]&.split(" ")&.first }
-        )
-        render json: { error: "Authentication required" }, status: 401
-        
-      rescue => e
-        Lapsoss.capture_exception(e, 
-          tags: { error_type: "unexpected_api_error" }
-        )
-        render json: { error: "Internal server error" }, status: 500
-      end
-      
-    end
-  end
-end
+# Multiple providers for redundancy
+config.use_sentry(name: :primary, dsn: ENV['PRIMARY_DSN'])
+config.use_rollbar(name: :backup, access_token: ENV['BACKUP_TOKEN'])
 ```
 
-> 💡 **Pro Tip**: Check out the `/examples` directory for more comprehensive configuration examples and use cases.
+## Yes, We Require ActiveSupport
 
-### Rollbar Integration
-```ruby
-# Traditional Rollbar setup:
-# rails generate rollbar YOUR_ACCESS_TOKEN
-
-# With Lapsoss:
-config.use_rollbar(
-  name: :rollbar,
-  access_token: ENV['ROLLBAR_ACCESS_TOKEN'] # or your token directly
-)
-```
+This is a Rails gem for Rails applications. We use ActiveSupport because:
+- You already have it (you're using Rails)
+- It provides the exact utilities we need
+- It's better than reimplementing Rails patterns poorly
 
-### Insight Hub Integration
-```ruby
-config.use_insight_hub(
-  name: :insight_hub,
-  api_key: ENV['INSIGHT_HUB_API_KEY'],
-  release_stage: Rails.env,
-  app_version: '1.0.0'
-)
-
-# For backwards compatibility, you can still use:
-# config.use_bugsnag(...) which maps to Insight Hub
-```
+If you need pure Ruby error tracking, use the vendor SDKs directly for now.
 
-## Advanced Features
+## Who This Is For
 
-### Custom Fingerprinting for Intelligent Error Grouping
+- Teams that have been burned by vendor lock-in
+- Apps that need regional data compliance (GDPR)
+- Developers who value clean, maintainable code
+- Rails applications that embrace change
 
-Lapsoss provides sophisticated error fingerprinting to group related errors together, reducing noise and improving debugging efficiency.
+## Who This Is NOT For
 
-#### Built-in Smart Patterns
-```ruby
-# These errors get automatically grouped:
-"User 123 not found"    } → "user-lookup-error"
-"User 456 not found"    }
+- Pure Ruby libraries (use vendor SDKs)
+- Teams happy with their current vendor forever
+- Applications that need APM features
+- Non-Rails applications
 
-"Payment processing failed for order #123" } → "payment-failure"  
-"Payment failed for card ending in 4567"   }
+## Supported Adapters
 
-"Database connection lost"     } → "database-connection-error"
-"PG::ConnectionBad: timeout"   }
-```
+All adapters are pure Ruby implementations with no external SDK dependencies:
 
-#### Custom Fingerprint Callbacks
-```ruby
-Lapsoss.configure do |config|
-  config.fingerprint_callback = lambda do |event|
-    case event.exception&.class&.name
-    when "ActiveRecord::RecordNotFound"
-      # Group all record not found errors
-      "database-record-error"
-    when /Net::/
-      # Group all network errors
-      "network-error"  
-    when "Redis::ConnectionError", "Redis::TimeoutError"
-      # Group Redis issues
-      "redis-error"
-    else
-      nil # Use default fingerprinting
-    end
-  end
-end
-```
+- **Sentry** - Full error tracking support
+- **Rollbar** - Complete error tracking with grouping
+- **AppSignal** - Error tracking and deploy markers
+- **Insight Hub** (formerly Bugsnag) - Error tracking with breadcrumbs
 
-#### Pattern-Based Fingerprinting
-```ruby
-Lapsoss.configure do |config|
-  config.fingerprint_patterns = [
-    # E-commerce patterns
-    {
-      pattern: /Payment.*failed/i,
-      fingerprint: "payment-failure"
-    },
-    {
-      pattern: /Order \d+ (invalid|missing|not found)/i,
-      fingerprint: "order-lookup-error"
-    },
-    
-    # API patterns  
-    {
-      pattern: %r{/api/v\d+/users/\d+},
-      fingerprint: "api-user-endpoint-error"
-    },
-    {
-      pattern: /Rate limit exceeded/i,
-      fingerprint: "rate-limit-exceeded"
-    }
-  ]
-end
-```
+## Configuration
 
-#### Smart Normalization
-```ruby
-Lapsoss.configure do |config|
-  # Normalize IDs: "User 12345 not found" → "User :id not found"
-  config.normalize_fingerprint_ids = true
-  
-  # Normalize paths: "/home/user/file.txt" → ":filepath"  
-  config.normalize_fingerprint_paths = true
-  
-  # Include environment in fingerprint (useful for staging vs production)
-  config.fingerprint_include_environment = false
-end
-```
+### Basic Setup
 
-#### Advanced Use Cases
 ```ruby
-# Environment-specific fingerprinting
-config.fingerprint_callback = lambda do |event|
-  if Rails.env.development?
-    # More detailed fingerprints for debugging
-    "#{event.exception.class.name}-#{event.exception.backtrace&.first}"
-  else
-    # Simpler fingerprints for production
-    case event.exception&.class&.name
-    when /ActiveRecord/ then "database-error"
-    when /Net::/ then "network-error"  
-    else nil
-    end
-  end
-end
-
-# Group by controller/model for Rails apps
-config.fingerprint_callback = lambda do |event|
-  backtrace = event.exception&.backtrace || []
-  
-  if controller_line = backtrace.find { |line| line.include?("app/controllers/") }
-    controller = controller_line.match(%r{app/controllers/(\w+)_controller\.rb})[1]
-    "controller-#{controller}-error"
-  elsif model_line = backtrace.find { |line| line.include?("app/models/") }
-    model = model_line.match(%r{app/models/(\w+)\.rb})[1] 
-    "model-#{model}-error"
-  else
-    nil
-  end
+# config/initializers/lapsoss.rb
+Lapsoss.configure do |config|
+  config.use_sentry(dsn: ENV["SENTRY_DSN"])
 end
 ```
 
-### Transport Reliability & Rate Limiting
-
-Lapsoss includes built-in transport reliability to ensure your errors reach their destination even under adverse conditions.
+### Multi-Adapter Setup
 
 ```ruby
 Lapsoss.configure do |config|
-  # Transport reliability settings
-  config.transport_timeout = 10          # Request timeout in seconds
-  config.transport_max_retries = 3       # Number of retry attempts
-  config.transport_initial_backoff = 1.0 # Initial backoff delay
-  config.transport_max_backoff = 64.0    # Maximum backoff delay
-  config.transport_backoff_multiplier = 2.0  # Exponential backoff multiplier
-  config.transport_jitter = true         # Add random jitter to prevent thundering herd
+  # Named adapters for different purposes
+  config.use_sentry(name: :errors, dsn: ENV['SENTRY_DSN'])
+  config.use_rollbar(name: :business_events, access_token: ENV['ROLLBAR_TOKEN'])
+  config.use_logger(name: :local_backup) # Local file backup
 end
 ```
 
-**Features:**
-- **Exponential Backoff**: Intelligent retry timing to avoid overwhelming services (transport layer)
-- **Rate Limiting**: Pipeline middleware with time-window and token bucket algorithms  
-- **Jitter**: Random delays to prevent synchronized retry storms (transport layer)
-- **Circuit Breaking**: Automatic failure detection and recovery (transport layer)
-
-### Backtrace Processing
-
-Lapsoss includes advanced backtrace processing that enhances error reports across all adapters:
+### Advanced Configuration
 
 ```ruby
 Lapsoss.configure do |config|
-  # Code context extraction
-  config.backtrace_context_lines = 3        # Lines of code context (before/after)
-  config.backtrace_enable_code_context = true  # Enable/disable context extraction
-  
-  # Path normalization
-  config.backtrace_strip_load_path = true   # Strip Ruby load paths for cleaner traces
-  
-  # Frame limiting (for deep stack traces)
-  config.backtrace_max_frames = 100         # Prevent memory issues with stack overflows
-  
-  # Application code detection
-  config.backtrace_in_app_patterns = [
-    %r{^/app/},                            # Rails app directory
-    %r{^lib/},                             # Custom libraries
-    %r{/my_company/}                       # Company code
-  ]
-  
-  # Noise filtering
-  config.backtrace_exclude_patterns = [
-    %r{/ruby/gems/.*/rack-},               # Rack internals
-    %r{/activesupport-.*/notifications},   # AS internals
-    %r{/newrelic_rpm/}                     # Monitoring gems
-  ]
-end
-```
+  # Adapter setup
+  config.use_sentry(dsn: ENV['SENTRY_DSN'])
 
-**Features:**
-- **Code Context**: Include source code snippets around error locations
-- **Smart Filtering**: Remove framework noise, focus on your code
-- **In-App Detection**: Automatically identify application vs library code
-- **Performance Optimized**: LRU file caching for efficient processing
-- **Format Agnostic**: Consistent processing across all adapters
+  # Data scrubbing (uses Rails filter_parameters automatically)
+  config.scrub_fields = %w[password credit_card ssn] # Or leave nil to use Rails defaults
 
-### Configuration Validation
+  # Error filtering
+  config.before_send = lambda do |event|
+    # Return nil to prevent sending
+    return nil if event.exception.is_a?(ActiveRecord::RecordNotFound)
+    event
+  end
 
-All adapter settings are validated to catch configuration errors early:
+  # Sampling
+  config.sample_rate = Rails.env.production? ? 0.25 : 1.0
 
-```ruby
-# ✅ Valid configurations
-config.use_sentry(dsn: "https://public_key@sentry.io/project_id")
-config.use_rollbar(access_token: "abc123def456")  
-config.use_appsignal(push_api_key: "12345678-1234-1234-1234-123456789abc")
-
-# ❌ Invalid configurations (caught at startup)
-config.use_sentry(dsn: "invalid-dsn")  # ValidationError: DSN scheme is required
-config.use_rollbar(access_token: "invalid@token")  # ValidationError: must be alphanumeric
-config.use_appsignal(push_api_key: "not-a-uuid")  # ValidationError: must be valid UUID
+  # Performance
+  config.async = true # Send errors in background
+  config.transport_timeout = 10 # seconds
+  config.transport_max_retries = 3
+end
 ```
 
-## Data Security & Privacy
+### Data Protection
 
-Lapsoss automatically protects sensitive data by integrating with Rails' parameter filtering system.
+Lapsoss automatically integrates with Rails' parameter filtering:
 
-### Automatic Rails Integration
 ```ruby
-# config/initializers/filter_parameter_logging.rb (Standard Rails)
-Rails.application.config.filter_parameters += [
-  :passw, :secret, :token, :_key, :crypt, :salt, :certificate, :otp, :ssn
-]
+# config/initializers/filter_parameter_logging.rb
+Rails.application.config.filter_parameters += [:password, :token]
 
 # Lapsoss automatically uses these filters - no additional configuration needed!
-Lapsoss.configure do |config|
-  config.use_sentry(dsn: ENV['SENTRY_DSN'])
-  # Sensitive fields are automatically scrubbed using Rails filter_parameters
-end
-```
-
-### Custom Data Scrubbing
-```ruby
-Lapsoss.configure do |config|
-  # Add custom fields to scrub (in addition to Rails filters)
-  config.scrub_fields = %w[internal_token custom_secret]
-  
-  # Override Rails filters completely
-  config.scrub_fields = %w[password api_key credit_card]  # Ignores Rails config
-  
-  # Scrub everything except whitelisted fields
-  config.scrub_all = true
-  config.whitelist_fields = %w[debug_info safe_field]
-  
-  # Randomize scrubbed value lengths (security through obscurity)
-  config.randomize_scrub_length = true  # "******" to "*********"
-end
 ```
 
-### What Gets Protected
-- **Passwords**: `password`, `passwd`, `pwd`
-- **Tokens**: `token`, `access_token`, `auth_token`, `csrf_token`
-- **Keys**: `key`, `api_key`, `secret_key`
-- **PII**: `ssn`, `social_security_number`, `credit_card`, `phone`
-- **File Uploads**: Metadata extracted, content scrubbed
-- **Rails filter_parameters**: Automatically respected
-
-## Adaptive Traits We've Selected
-
-### From Sentry 🔍
-- **Custom fingerprinting** for intelligent error grouping
-- Robust error capture with context
-- Release tracking and environment awareness
-
-### From Rollbar 🎲
-- **Advanced data scrubbing** with Rails parameter filter integration
-- **Transport reliability** with exponential backoff and retry logic
-- Person tracking and user context
+### Custom Fingerprinting
 
-### From AppSignal 📊
-- **Configuration validation** to catch setup errors early
-- Check-in monitoring for cron jobs
-- Deploy markers and health checks
+Control how errors are grouped:
 
-### From Insight Hub (formerly Bugsnag) 🐛
-- Feature flag correlation with errors
-- Session tracking for crash-free rates
-- Typed breadcrumbs for debugging context
-
-
-### Lapsoss Innovations 🧬
-- **Pure Ruby implementations** - no external SDK dependencies
-- **Multi-adapter architecture** - use multiple services simultaneously
-- **Vendor-neutral configuration** - switch providers without code changes
-- **Zero monkey-patching** - your application remains untouched
-
-## Usage Examples
-
-### Basic Error Capture
 ```ruby
-begin
-  risky_operation
-rescue => e
-  Lapsoss.capture_exception(e, user: current_user)
+config.fingerprint_callback = lambda do |event|
+  case event.exception&.class&.name
+  when "ActiveRecord::RecordNotFound"
+    "record-not-found" # Group all together
+  when "Stripe::CardError"
+    "payment-failure"
+  else
+    nil # Use default fingerprinting
+  end
 end
 ```
 
-### Custom Fingerprinting in Action
-```ruby
-# These errors will be automatically grouped:
-begin
-  User.find(123)  # → "user-lookup-error"
-rescue ActiveRecord::RecordNotFound => e
-  Lapsoss.capture_exception(e)
-end
+### Transport Reliability
 
-begin
-  User.find(456)  # → Same "user-lookup-error" group
-rescue ActiveRecord::RecordNotFound => e
-  Lapsoss.capture_exception(e)
-end
-```
+Built-in retry logic with exponential backoff:
 
-### Advanced Configuration Example
 ```ruby
-Lapsoss.configure do |config|
-  # Multi-vendor setup with custom fingerprinting
-  config.use_sentry(name: :sentry, dsn: ENV['SENTRY_DSN'])
-  config.use_rollbar(name: :rollbar, access_token: ENV['ROLLBAR_TOKEN'])
-  
-  # Custom fingerprinting for your domain
-  config.fingerprint_callback = lambda do |event|
-    case event.exception&.message
-    when /payment.*failed/i
-      "payment-processing-error"
-    when /user.*not.*found/i  
-      "user-lookup-error"
-    else
-      nil # Use built-in patterns and defaults
-    end
-  end
-  
-  # Enhanced data protection
-  config.scrub_fields = %w[credit_card_number api_token internal_id]
-  config.randomize_scrub_length = true
-  
-  # Reliable transport
-  config.transport_max_retries = 5
-  config.transport_timeout = 15
-end
+config.transport_max_retries = 3
+config.transport_timeout = 10
+config.transport_jitter = true # Prevent thundering herd
 ```
 
-
 ## Creating Custom Adapters
 
 ```ruby
-class MyCustomAdapter < Lapsoss::Adapters::Base
+class MyAdapter < Lapsoss::Adapters::Base
   def capture(event)
     # Send to your service
+    HttpClient.post("/errors", event.to_h)
   end
 end
 
-Lapsoss::Registry.register(:custom, MyCustomAdapter)
-```
-
-## Multi-Adapter Use Cases
-
-### GDPR Region Migration
-```ruby
-# Step 1: Start with US
-config.use_sentry(name: :sentry_us, dsn: ENV['SENTRY_US_DSN'])
-
-# Step 2: Add EU, run both
-config.use_sentry(name: :sentry_us, dsn: ENV['SENTRY_US_DSN'])
-config.use_sentry(name: :sentry_eu, dsn: ENV['SENTRY_EU_DSN'])
-
-# Step 3: Complete migration
-config.use_sentry(name: :sentry_eu, dsn: ENV['SENTRY_EU_DSN'])
-```
-
-### Vendor Migration
-```ruby
-# Gradual migration with zero downtime
-config.use_bugsnag(name: :old_vendor, api_key: ENV['BUGSNAG_KEY'])
-config.use_sentry(name: :new_vendor, dsn: ENV['SENTRY_DSN'])
-# Remove old vendor when ready
+Lapsoss::Registry.register(:my_service, MyAdapter)
 ```
 
-### AppSignal Integration
-```ruby
-# config/initializers/lapsoss.rb
-config.use_appsignal(
-  name: :appsignal,
-  push_api_key: ENV['APPSIGNAL_PUSH_API_KEY'],        # For markers & check-ins
-  frontend_api_key: ENV['APPSIGNAL_FRONTEND_API_KEY'], # For error tracking
-  app_name: 'my-app'
-)
-```
-
-**AppSignal API Keys**: AppSignal uses two different API keys:
-- **Push API Key**: For deploy markers and check-ins (found in Push & Deploy settings)
-- **Frontend API Key**: For error tracking via public API (found in App settings > "Front-end error monitoring")
-
-The Lapsoss AppSignal adapter provides:
-- ✅ Error tracking (via public `/errors` endpoint with frontend key)
-- ✅ Deploy markers (via `/markers` endpoint with push key)
-- ✅ Check-ins/Heartbeats (via `/heartbeats` endpoint with push key)
-- ✅ Breadcrumbs (included with errors)
-- ❌ Performance monitoring (requires native extension)
-- ❌ Host metrics (requires native extension)
-
-### High Availability
-```ruby
-# Multiple regions + vendors for redundancy
-config.use_sentry(name: :primary, dsn: ENV['PRIMARY_DSN'])
-config.use_sentry(name: :backup, dsn: ENV['BACKUP_DSN'])
-config.use_rollbar(name: :backup_service, access_token: ENV['ROLLBAR_TOKEN'])
-```
-
-## Why "Adaptive Trait Selection"?
-
-Traditional error tracking gems lock you into their ecosystem. Lapsoss applies evolutionary principles:
-
-1. **Observation**: Each vendor evolved unique strengths
-2. **Selection**: I identify the most beneficial traits
-3. **Adaptation**: I create vendor-neutral interfaces
-4. **Evolution**: Your app gains the best of all worlds
-
-### The Multi-Adapter Advantage
-
-- **Zero-downtime migrations** between providers
-- **Regional compliance** (GDPR, data residency)
-- **Vendor independence** - never locked in
-- **Cost optimization** - route by importance
-- **A/B testing** different services
-
 ## Contributing
 
-Help me evolve! I'm actively selecting new adaptive traits:
-
-1. Fork the repo
+1. Fork it
 2. Create your feature branch
-3. Add your trait selection
-4. Submit a PR
+3. Add tests for your changes
+4. Submit a pull request
 
 ## License
 
-MIT License - Because good traits should spread freely
+MIT License - Because good code should be free
 
 ---
 
-Built with ❤️ and evolutionary principles
+Built for Rails developers who refuse to be locked in.