lapsoss 0.4.0 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0faf08671ef4e1b0b36ccc9e29900b8e8b5e4a78ac61ffea6269294efee5881
-  data.tar.gz: b2c76c33817f3a939388970d21c5fc341ad6ce46e0ce20ef9b71ca5b5c565ae0
+  metadata.gz: 3c9422cb2f9fa0e1ae582a771fd337d61177d9236db6cd3dfc96edf3fefc7777
+  data.tar.gz: d1dc595b8fcd5e00feb9f01087e77700bb49452a6b358a309ce630d6b29bd203
 SHA512:
-  metadata.gz: 5cfb22826215ffc2473410d6e984ecbd93f74ec0c011e742d7246549b29c1d77b9cb81c774cab311748c0b39cbfd9b9eccfdbb4324aa6da7a632ba8634eb3b19
-  data.tar.gz: f641a491be8007a0bc6780094803724f66efc79aa1e10cadbb1ac96c84a8ff30af119c763e1611dc3e2218305c4d0b5958b6f5c5f2863c7b5694b5ff7c9f0856
+  metadata.gz: 218bbe054b15df5457996cfda82aa6227477446dc0a5be24680acbae4c4ff3edfaf7217adfc96814aba94fe09331300253f4a499a85055b2fbac8df83a8336fb
+  data.tar.gz: d5b0f10802bfe6c938cf90e8a322b0bc940b11d3bca9fde5efcaf96964c5753c09e04ae453087844cb455056b2cd6fd242e846e99ce59270d25962367daa7bda

data/README.md

@@ -163,6 +163,7 @@ All adapters are pure Ruby implementations with no external SDK dependencies:
 - **Rollbar** - Complete error tracking with grouping
 - **AppSignal** - Error tracking and deploy markers
 - **Insight Hub** (formerly Bugsnag) - Error tracking with breadcrumbs
+- **Telebug** - Sentry-compatible protocol (perfect for self-hosted alternatives)
 
 ## Configuration
 
@@ -186,6 +187,17 @@ Lapsoss.configure do |config|
 end
 ```
 
+### Using Sentry-Compatible Services
+
+```ruby
+# Telebug, Glitchtip, or any Sentry-compatible service
+Lapsoss.configure do |config|
+  config.use_telebug(dsn: ENV['TELEBUG_DSN'])
+  # Or use use_sentry with a custom endpoint
+  config.use_sentry(dsn: ENV['SELF_HOSTED_SENTRY_DSN'])
+end
+```
+
 ### Advanced Configuration
 
 ```ruby
@@ -196,23 +208,82 @@ Lapsoss.configure do |config|
   # Data scrubbing (uses Rails filter_parameters automatically)
   config.scrub_fields = %w[password credit_card ssn] # Or leave nil to use Rails defaults
 
-  # Error filtering
+  # Performance
+  config.async = true # Send errors in background
+
+  # Sampling (see docs/sampling_strategies.md for advanced examples)
+  config.sample_rate = Rails.env.production? ? 0.25 : 1.0
+  
+  # Transport settings
+  config.transport_timeout = 10 # seconds
+  config.transport_max_retries = 3
+end
+```
+
+### Filtering Errors
+
+You decide what errors to track. Lapsoss doesn't make assumptions:
+
+```ruby
+Lapsoss.configure do |config|
+  # Use the before_send callback for simple filtering
   config.before_send = lambda do |event|
     # Return nil to prevent sending
     return nil if event.exception.is_a?(ActiveRecord::RecordNotFound)
     event
   end
+  
+  # Or use the exclusion filter for more complex rules
+  config.exclusion_filter = Lapsoss::ExclusionFilter.new(
+    # Exclude specific exception types
+    excluded_exceptions: [
+      "ActionController::RoutingError",  # Your choice
+      "ActiveRecord::RecordNotFound"     # Your decision
+    ],
+    
+    # Exclude by pattern matching
+    excluded_patterns: [
+      /timeout/i,           # If timeouts are expected in your app
+      /user not found/i     # If these are normal in your workflow
+    ],
+    
+    # Exclude specific error messages
+    excluded_messages: [
+      "No route matches",
+      "Invalid authenticity token"
+    ]
+  )
+  
+  # Add custom exclusion logic
+  config.exclusion_filter.add_exclusion(:custom, lambda do |event|
+    # Your business logic here
+    event.context[:request]&.dig(:user_agent)&.match?(/bot/i)
+  end)
+end
+```
 
-  # Sampling
-  config.sample_rate = Rails.env.production? ? 0.25 : 1.0
+#### Common Patterns (Your Choice)
 
-  # Performance
-  config.async = true # Send errors in background
-  config.transport_timeout = 10 # seconds
-  config.transport_max_retries = 3
+```ruby
+# Development/Test exclusions
+if Rails.env.development?
+  config.exclusion_filter.add_exclusion(:exception, "RSpec::Expectations::ExpectationNotMetError")
+  config.exclusion_filter.add_exclusion(:exception, "Minitest::Assertion")
 end
+
+# User input errors (if you don't want to track them)
+config.exclusion_filter.add_exclusion(:exception, "ActiveRecord::RecordInvalid")
+config.exclusion_filter.add_exclusion(:exception, "ActionController::ParameterMissing")
+
+# Bot traffic (if you want to exclude it)
+config.exclusion_filter.add_exclusion(:custom, lambda do |event|
+  request = event.context[:request]
+  request && request[:user_agent]&.match?(/googlebot|bingbot/i)
+end)
 ```
 
+Your app, your rules. Lapsoss just provides the mechanism.
+
 ### Data Protection
 
 Lapsoss automatically integrates with Rails' parameter filtering:
@@ -251,6 +322,103 @@ config.transport_timeout = 10
 config.transport_jitter = true # Prevent thundering herd
 ```
 
+## Testing in Rails Console
+
+Want to see Lapsoss in action? Try this in your Rails console:
+
+```ruby
+# Configure Lapsoss with the logger adapter for immediate visibility
+Lapsoss.configure do |config|
+  config.use_logger(name: :console_test)
+  config.async = false  # Synchronous for immediate output
+  config.debug = true   # Verbose logging
+end
+
+# Create a class that demonstrates error handling
+class Liberation
+  def self.liberate!
+    Rails.error.handle do
+      raise StandardError, "Freedom requires breaking chains!"
+    end
+    puts "✅ Continued execution after error"
+  end
+  
+  def self.revolt!
+    Rails.error.record do
+      raise RuntimeError, "Revolution cannot be stopped!"
+    end
+    puts "This won't print - error was re-raised"
+  end
+end
+
+# Test error capture (error is swallowed)
+Liberation.liberate!
+# You'll see the error logged but execution continues
+
+# Test error recording (error is re-raised)
+begin
+  Liberation.revolt!
+rescue => e
+  puts "Caught re-raised error: #{e.message}"
+end
+
+# Manual error reporting with context
+begin
+  1 / 0
+rescue => e
+  Rails.error.report(e, context: { user_id: 42, action: "console_test" })
+end
+
+# Check what was captured
+puts "\n🎉 Lapsoss captured all errors through Rails.error!"
+```
+
+You'll see all errors logged to your console with full backtraces and context. This same integration works automatically for all Rails controllers, jobs, and mailers.
+
+## Using Lapsoss Outside Rails
+
+Lapsoss provides the same convenient error handling methods directly, perfect for background jobs, rake tasks, or standalone scripts:
+
+```ruby
+# In your Sidekiq job, rake task, or any Ruby code
+require 'lapsoss'
+
+Lapsoss.configure do |config|
+  config.use_sentry(dsn: ENV['SENTRY_DSN'])
+end
+
+# Handle errors (swallow them)
+result = Lapsoss.handle do
+  risky_operation
+end
+# Returns nil if error occurred, or the block's result
+
+# Handle with fallback
+user = Lapsoss.handle(fallback: User.anonymous) do
+  User.find(id)
+end
+
+# Record errors (re-raise them)
+Lapsoss.record do
+  critical_operation  # Error is captured then re-raised
+end
+
+# Report errors manually
+begin
+  something_dangerous
+rescue => e
+  Lapsoss.report(e, user_id: user.id, context: 'background_job')
+  # Continue processing...
+end
+
+# These methods mirror Rails.error exactly:
+# - Lapsoss.handle   → Rails.error.handle
+# - Lapsoss.record   → Rails.error.record  
+# - Lapsoss.report   → Rails.error.report
+```
+
+This means your error handling code works the same way everywhere - in Rails controllers, background jobs, rake tasks, or standalone scripts.
+
 ## Creating Custom Adapters
 
 ```ruby
@@ -264,6 +432,26 @@ end
 Lapsoss::Registry.register(:my_service, MyAdapter)
 ```
 
+### Extending Existing Adapters
+
+For Sentry-compatible services, just extend the SentryAdapter:
+
+```ruby
+class TelebugAdapter < Lapsoss::Adapters::SentryAdapter
+  def initialize(name = :telebug, settings = {})
+    super(name, settings)
+  end
+  
+  private
+  
+  def build_headers(public_key)
+    super(public_key).merge(
+      "X-Telebug-Client" => "lapsoss/#{Lapsoss::VERSION}"
+    )
+  end
+end
+```
+
 ## Contributing
 
 1. Fork it

data/lib/lapsoss/adapters/concerns/level_mapping.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "active_support/concern"
+require "active_support/core_ext/class/attribute"
 require "active_support/core_ext/hash/indifferent_access"
 
 module Lapsoss

data/lib/lapsoss/adapters/telebug_adapter.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "sentry_adapter"
+
+module Lapsoss
+  module Adapters
+    # Telebug adapter - uses Sentry protocol with Telebug endpoints
+    # Telebug is compatible with Sentry's API, so we inherit from SentryAdapter
+    class TelebugAdapter < SentryAdapter
+      def initialize(name = :telebug, settings = {})
+        super(name, settings)
+      end
+
+      private
+
+      # Override to parse Telebug DSN format
+      def parse_dsn(dsn_string)
+        uri = URI.parse(dsn_string)
+        {
+          public_key: uri.user,
+          project_id: uri.path.split("/").last,
+          host: uri.host,
+          path: uri.path
+        }
+      end
+
+      # Override to build Telebug-specific API path
+      def build_api_path(uri)
+        # Telebug uses: https://[key]@[host]/api/v1/sentry_errors/[project_id]
+        # The path is already complete: /api/v1/sentry_errors/4
+        # Unlike Sentry which needs /api/[project_id]/envelope/
+        uri.path
+      end
+
+      # Override to setup Telebug endpoint
+      def setup_endpoint
+        uri = URI.parse(@settings[:dsn])
+        # For Telebug, we use the full URL without port (unless non-standard)
+        port = (uri.port == 443 || uri.port == 80) ? "" : ":#{uri.port}"
+        self.class.api_endpoint = "#{uri.scheme}://#{uri.host}#{port}"
+        self.class.api_path = build_api_path(uri)
+      end
+
+      # Override headers builder to add Telebug-specific headers
+      def headers_for(envelope)
+        base_headers = super(envelope)
+        base_headers.merge(
+          "X-Telebug-Client" => "lapsoss/#{Lapsoss::VERSION}"
+        )
+      end
+
+      # Override user agent for Telebug
+      def user_agent
+        "lapsoss-telebug/#{Lapsoss::VERSION}"
+      end
+    end
+  end
+end

data/lib/lapsoss/client.rb

@@ -103,9 +103,7 @@ module Lapsoss
     end
 
     def handle_capture_error(error)
-      return unless @configuration.logger
-
-      @configuration.logger.error("[Lapsoss] Failed to capture event: #{error.message}")
+      @configuration.logger.error("Failed to capture event: #{error.message}")
     end
   end
 end

data/lib/lapsoss/configuration.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "logger"
 require "active_support/configurable"
 
 module Lapsoss
@@ -21,7 +22,7 @@ module Lapsoss
     def initialize
       @adapter_configs = {}
       @async = true
-      @logger = nil
+      @logger = Logger.new(nil) # Default null logger
       @environment = nil
       @enabled = true
       @release = nil
@@ -84,6 +85,11 @@ module Lapsoss
       register_adapter(name, :sentry, **settings)
     end
 
+    # Convenience method for Telebug (Sentry-compatible)
+    def use_telebug(name: :telebug, **settings)
+      register_adapter(name, :telebug, **settings)
+    end
+
     # Convenience method for AppSignal
     def use_appsignal(name: :appsignal, **settings)
       register_adapter(name, :appsignal, **settings)
@@ -193,17 +199,8 @@ module Lapsoss
 
     def create_sampling_strategy
       case @sampling_strategy
-      when Symbol
-        case @sampling_strategy
-        when :production
-          Sampling::SamplingFactory.create_production_sampling
-        when :development
-          Sampling::SamplingFactory.create_development_sampling
-        when :user_focused
-          Sampling::SamplingFactory.create_user_focused_sampling
-        else
-          Sampling::UniformSampler.new(@sample_rate)
-        end
+      when Numeric
+        Sampling::UniformSampler.new(@sampling_strategy)
       when Proc
         @sampling_strategy
       when nil
@@ -276,7 +273,7 @@ module Lapsoss
     def validate!
       # Check sample rate is between 0 and 1
       if @sample_rate && (@sample_rate < 0 || @sample_rate > 1)
-        logger&.warn "[Lapsoss] sample_rate should be between 0 and 1, got #{@sample_rate}"
+        logger.warn "sample_rate should be between 0 and 1, got #{@sample_rate}"
       end
 
       # Check callables
@@ -289,21 +286,21 @@ module Lapsoss
 
       # Just log if transport settings look unusual
       if @transport_timeout && @transport_timeout <= 0
-        logger&.warn "[Lapsoss] transport_timeout should be positive, got #{@transport_timeout}"
+        logger.warn "transport_timeout should be positive, got #{@transport_timeout}"
       end
 
       if @transport_max_retries && @transport_max_retries < 0
-        logger&.warn "[Lapsoss] transport_max_retries should be non-negative, got #{@transport_max_retries}"
+        logger.warn "transport_max_retries should be non-negative, got #{@transport_max_retries}"
       end
 
       if @transport_initial_backoff && @transport_max_backoff && @transport_initial_backoff > @transport_max_backoff
-        logger&.warn "[Lapsoss] transport_initial_backoff (#{@transport_initial_backoff}) should be less than transport_max_backoff (#{@transport_max_backoff})"
+        logger.warn "transport_initial_backoff (#{@transport_initial_backoff}) should be less than transport_max_backoff (#{@transport_max_backoff})"
       end
 
       # Validate adapter configurations exist
       @adapter_configs.each do |name, config|
         if config[:type].blank?
-          logger&.warn "[Lapsoss] Adapter '#{name}' has no type specified"
+          logger.warn "Adapter '#{name}' has no type specified"
         end
       end
 

data/lib/lapsoss/fingerprinter.rb

@@ -4,8 +4,9 @@ require "digest"
 
 module Lapsoss
   class Fingerprinter
-    DEFAULT_PATTERNS = [
-      # User/ID normalization patterns
+    # Base patterns that are always available
+    BASE_PATTERNS = [
+      # Generic error message normalization
       {
         pattern: /User \d+ (not found|invalid|missing)/i,
         fingerprint: "user-lookup-error"
@@ -15,21 +16,25 @@ module Lapsoss
         fingerprint: "record-lookup-error"
       },
 
-      # URL/Path normalization patterns
+      # Network error patterns
       {
-        pattern: %r{/users/\d+(/.*)?},
-        fingerprint: "users-id-endpoint"
+        pattern: /Net::(TimeoutError|ReadTimeout|OpenTimeout)/,
+        fingerprint: "network-timeout"
       },
       {
-        pattern: %r{/api/v\d+/.*},
-        fingerprint: "api-endpoint"
+        pattern: /Errno::(ECONNREFUSED|ECONNRESET|EHOSTUNREACH)/,
+        fingerprint: "network-connection-error"
       },
 
-      # Database error patterns
+      # Memory/Resource patterns
       {
-        pattern: /PG::ConnectionBad|Mysql2::Error|SQLite3::BusyException/,
-        fingerprint: "database-connection-error"
-      },
+        pattern: /NoMemoryError|SystemStackError/,
+        fingerprint: "memory-resource-error"
+      }
+    ].freeze
+
+    # ActiveRecord-specific patterns (only loaded if ActiveRecord is defined)
+    ACTIVERECORD_PATTERNS = [
       {
         pattern: /ActiveRecord::RecordNotFound/,
         fingerprint: "record-not-found"
@@ -38,38 +43,34 @@ module Lapsoss
         pattern: /ActiveRecord::StatementInvalid.*timeout/i,
         fingerprint: "database-timeout"
       },
-
-      # Network error patterns
-      {
-        pattern: /Net::(TimeoutError|ReadTimeout|OpenTimeout)/,
-        fingerprint: "network-timeout"
-      },
       {
-        pattern: /Errno::(ECONNREFUSED|ECONNRESET|EHOSTUNREACH)/,
-        fingerprint: "network-connection-error"
-      },
+        pattern: /ActiveRecord::ConnectionTimeoutError/,
+        fingerprint: "database-connection-timeout"
+      }
+    ].freeze
 
-      # File system patterns
+    # Database adapter patterns (only loaded if adapters are defined)
+    DATABASE_PATTERNS = [
       {
-        pattern: %r{Errno::(ENOENT|EACCES).*/tmp/},
-        fingerprint: "tmp-file-error"
+        pattern: /PG::ConnectionBad/,
+        fingerprint: "postgres-connection-error",
+        condition: -> { defined?(PG) }
       },
       {
-        pattern: /No such file or directory.*\.log/,
-        fingerprint: "log-file-missing"
+        pattern: /Mysql2::Error/,
+        fingerprint: "mysql-connection-error",
+        condition: -> { defined?(Mysql2) }
       },
-
-      # Memory/Resource patterns
       {
-        pattern: /NoMemoryError|SystemStackError/,
-        fingerprint: "memory-resource-error"
+        pattern: /SQLite3::BusyException/,
+        fingerprint: "sqlite-busy-error",
+        condition: -> { defined?(SQLite3) }
       }
     ].freeze
 
     def initialize(config = {})
       @custom_callback = config[:custom_callback]
-      @patterns = config[:patterns] || DEFAULT_PATTERNS
-      @normalize_paths = config.fetch(:normalize_paths, true)
+      @patterns = build_patterns(config[:patterns])
       @normalize_ids = config.fetch(:normalize_ids, true)
       @include_environment = config.fetch(:include_environment, false)
     end
@@ -91,6 +92,23 @@ module Lapsoss
 
     private
 
+    def build_patterns(custom_patterns)
+      return custom_patterns if custom_patterns
+
+      patterns = BASE_PATTERNS.dup
+
+      # Always include ActiveRecord patterns - they match on string names
+      patterns.concat(ACTIVERECORD_PATTERNS)
+
+      # Add database-specific patterns - they also match on string names
+      DATABASE_PATTERNS.each do |pattern_config|
+        # Skip the condition check - just match on error names
+        patterns << pattern_config.except(:condition)
+      end
+
+      patterns
+    end
+
     def match_patterns(event)
       full_error_text = build_error_text(event)
 
@@ -170,18 +188,9 @@ module Lapsoss
 
         # Replace numeric IDs with placeholder (after UUIDs and hashes)
         normalized.gsub!(/\b\d{3,}\b/, ":id")
-      end
-
-      if @normalize_paths
-        # Replace absolute file paths with placeholder
-        normalized.gsub!(%r{/[^/\s]+(?:/[^/\s]+)*\.[a-zA-Z0-9]+}, ":filepath")
-        normalized.gsub!(%r{/[^/\s]+(?:/[^/\s]+)+(?:/)?}, ":dirpath")
 
         # Replace timestamps
         normalized.gsub!(/\b\d{4}-\d{2}-\d{2}[T\s]\d{2}:\d{2}:\d{2}/, ":timestamp")
-
-        # Replace URLs with placeholder
-        normalized.gsub!(%r{https?://[^\s]+}, ":url")
       end
 
       # Clean up extra whitespace
@@ -201,13 +210,9 @@ module Lapsoss
 
       line_to_use = app_line || backtrace.first
 
-      if @normalize_paths
-        # Extract just filename:line_number
-        if line_to_use =~ %r{([^/]+):(\d+)}
-          "#{::Regexp.last_match(1)}:#{::Regexp.last_match(2)}"
-        else
-          line_to_use
-        end
+      # Extract just filename:line_number
+      if line_to_use =~ %r{([^/]+):(\d+)}
+        "#{::Regexp.last_match(1)}:#{::Regexp.last_match(2)}"
       else
         line_to_use
       end