lapsoss 0.1.0

data/README.md

@@ -0,0 +1,855 @@
+# Lapsoss 🧬
+
+**Adaptive Trait Selection for Error Tracking**
+
+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.
+
+## Philosophy
+
+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:
+
+- **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
+
+```ruby
+gem 'lapsoss'
+```
+
+## Quick Start
+
+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
+
+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.
+
+### 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"])
+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
+
+# 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.
+```
+
+## Usage
+
+### Core API
+
+Lapsoss provides a simple, intuitive API for error tracking:
+
+```ruby
+# Capture exceptions
+Lapsoss.capture_exception(exception, **context)
+
+# Capture messages
+Lapsoss.capture_message(message, level: :info, **context)
+
+# 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"])
+end
+
+# That's it! All unhandled exceptions are automatically captured
+# No need to modify your controllers or models
+```
+
+### Manual Error Capture
+
+For non-Rails applications or custom error handling:
+
+```ruby
+# Basic exception capture
+begin
+  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
+```
+
+### Message Logging
+
+For important events or custom alerts:
+
+```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" }
+)
+```
+
+### Breadcrumbs for Debugging
+
+Track user actions and system events leading up to errors:
+
+```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
+```
+
+### Scoped Context
+
+Use scoped context to apply data to multiple operations:
+
+```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
+```
+
+### Real-World Examples
+
+#### E-commerce Checkout Flow
+```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
+```
+
+#### Background Job Error Handling
+```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
+```
+
+#### API Error Tracking
+```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
+```
+
+> 💡 **Pro Tip**: Check out the `/examples` directory for more comprehensive configuration examples and use cases.
+
+### 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
+)
+```
+
+### 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
+```
+
+## Advanced Features
+
+### Custom Fingerprinting for Intelligent Error Grouping
+
+Lapsoss provides sophisticated error fingerprinting to group related errors together, reducing noise and improving debugging efficiency.
+
+#### Built-in Smart Patterns
+```ruby
+# These errors get automatically grouped:
+"User 123 not found"    } → "user-lookup-error"
+"User 456 not found"    }
+
+"Payment processing failed for order #123" } → "payment-failure"  
+"Payment failed for card ending in 4567"   }
+
+"Database connection lost"     } → "database-connection-error"
+"PG::ConnectionBad: timeout"   }
+```
+
+#### 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
+```
+
+#### 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
+```
+
+#### 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
+```
+
+#### 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
+end
+```
+
+### Transport Reliability & Rate Limiting
+
+Lapsoss includes built-in transport reliability to ensure your errors reach their destination even under adverse conditions.
+
+```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
+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:
+
+```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
+```
+
+**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
+
+### Configuration Validation
+
+All adapter settings are validated to catch configuration errors early:
+
+```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
+```
+
+## Data Security & Privacy
+
+Lapsoss automatically protects sensitive data by integrating with Rails' parameter filtering system.
+
+### 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
+]
+
+# 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
+
+### From AppSignal 📊
+- **Configuration validation** to catch setup errors early
+- Check-in monitoring for cron jobs
+- Deploy markers and health checks
+
+### 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)
+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
+
+begin
+  User.find(456)  # → Same "user-lookup-error" group
+rescue ActiveRecord::RecordNotFound => e
+  Lapsoss.capture_exception(e)
+end
+```
+
+### 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
+```
+
+
+## Creating Custom Adapters
+
+```ruby
+class MyCustomAdapter < Lapsoss::Adapters::Base
+  def capture(event)
+    # Send to your service
+  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
+```
+
+### 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
+2. Create your feature branch
+3. Add your trait selection
+4. Submit a PR
+
+## License
+
+MIT License - Because good traits should spread freely
+
+---
+
+Built with ❤️ and evolutionary principles