lapsoss 0.4.10 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76c4609d94f1d9463922da6d1850b7b618977075dd0d96fa7d94d58186cd64b9
-  data.tar.gz: 8d5db54e63ef1e6a0d73962261bd13ce4cfca305c63570bf879c4dbf85bb3110
+  metadata.gz: 7c8f5f1fbdb514808ad6accd57f448a1d997f86f8c53224456421879e78ee40e
+  data.tar.gz: ee76c128c4b6f7b0f7d51ff81700258d6a8e1fbde522400009fa682b49658c7f
 SHA512:
-  metadata.gz: ac8bc565e2d54b1c3f600de8b2a6fedc0e2da481ce3c9003c587b81bd4134209618ba77dd3ae1019188537217c09c2f8317640ea36d46b91a229116eeaafd032
-  data.tar.gz: eee117f27719db7cfe019466cfbe5ec1210e86c0cfb0a7bff6764984acb148fb2233dd0c84fb7029e0e643e38f2147989f41172035a41dbd79a35eecad79763f
+  metadata.gz: '0591e240fabe7f68e179a09f55d61bc03f26374ca7abd28bc4f5a67789644670342ef43d7f56ebff6c3e409e7df18fd77ae11e82ae5d6fe44af582add4e20efb'
+  data.tar.gz: f85e9148f94abe28ff69693169fc600641c99cf1d2f0d0204b95c3c3582e039d5fab19cc9a7b8442e09dd72b2d2c2ce33f71339d0967b068a3c1363dab583bd5

data/README.md

@@ -39,7 +39,7 @@ end
 ## Requirements
 
 - Ruby 3.3+
-- Rails 7.2+
+- Rails 8.1+
 
 ## Installation
 
@@ -69,7 +69,7 @@ That's it. No 500-line examples needed.
 
 ## Built for Rails, Not Around It
 
-Lapsoss integrates with Rails' native error reporting API introduced in Rails 7. No monkey-patching, no global error handlers:
+Lapsoss integrates with Rails' native error reporting API (`Rails.error`). No monkey-patching, no global error handlers:
 
 ```ruby
 # It just works with Rails.error:
@@ -116,6 +116,51 @@ end
 
 # Or use Rails.error directly with your configured services
 Rails.error.report(e, context: { user_id: current_user.id })
+
+# For "should never happen" paths, Rails.error.unexpected raises in
+# development/test and reports in production - and routes through Lapsoss too
+Rails.error.unexpected("Reached unreachable branch")
+```
+
+### Structured Events as Breadcrumbs
+
+Lapsoss automatically subscribes to the structured event reporter
+(`Rails.event`) and records emitted events as breadcrumbs. When an error is
+captured, the recent activity trail is attached to the report - no
+monkey-patching, just Rails' native API:
+
+```ruby
+Rails.event.notify("order.checkout_started", cart_id: cart.id)
+# ... an exception here includes that breadcrumb in the error report
+
+# Tags and context flow into breadcrumb metadata
+Rails.event.tagged(section: "checkout") do
+  Rails.event.notify("payment.authorized", amount: 42_00)
+end
+```
+
+Tune or disable it:
+
+```ruby
+Lapsoss.configure do |config|
+  config.capture_rails_events = false                            # opt out entirely
+  config.rails_event_filter = ->(event) { !event[:name].start_with?("noisy.") }
+end
+```
+
+Rails-side enrichment also composes: context added via `Rails.error.add_middleware`
+flows into the `context:` Lapsoss receives for free.
+
+### Silencing Capture
+
+Suppress delivery for a block (thread-local) - useful in tests or around
+expected-failure paths. Breadcrumbs and scope still accumulate; only delivery
+is skipped:
+
+```ruby
+Lapsoss.silence do
+  retry_flaky_third_party_call
+end
 ```
 
 ### No Global Patching Philosophy
@@ -220,6 +265,8 @@ All adapters are pure Ruby implementations with no external SDK dependencies:
 - **AppSignal** - Error tracking and deploy markers
 - **Insight Hub** (formerly Bugsnag) - Error tracking with breadcrumbs
 - **Telebugs** - Sentry-compatible protocol (perfect for self-hosted alternatives)
+- **OpenObserve** - Open-source observability platform (logs, metrics, traces)
+- **OTLP** - OpenTelemetry Protocol (works with SigNoz, Jaeger, Tempo, Honeycomb, etc.)
 
 ## Configuration
 
@@ -254,6 +301,39 @@ Lapsoss.configure do |config|
 end
 ```
 
+### Using OpenObserve
+
+```ruby
+# OpenObserve - open-source observability platform
+Lapsoss.configure do |config|
+  config.use_openobserve(
+    endpoint: ENV['OPENOBSERVE_ENDPOINT'],  # e.g., "http://localhost:5080"
+    username: ENV['OPENOBSERVE_USERNAME'],
+    password: ENV['OPENOBSERVE_PASSWORD'],
+    org: "default",      # optional, defaults to "default"
+    stream: "errors"     # optional, defaults to "errors"
+  )
+end
+```
+
+### Using OTLP (OpenTelemetry Protocol)
+
+```ruby
+# Works with SigNoz, Jaeger, Tempo, Honeycomb, Datadog, etc.
+Lapsoss.configure do |config|
+  config.use_otlp(
+    endpoint: ENV['OTLP_ENDPOINT'],     # e.g., "http://localhost:4318"
+    service_name: "my-rails-app",
+    headers: { "X-Custom-Header" => "value" }  # optional custom headers
+  )
+
+  # Or use convenience helpers for specific services
+  config.use_signoz(signoz_api_key: ENV['SIGNOZ_API_KEY'])
+  config.use_jaeger(endpoint: "http://jaeger:4318")
+  config.use_tempo(endpoint: "http://tempo:4318")
+end
+```
+
 ### Advanced Configuration
 
 ```ruby
@@ -276,9 +356,27 @@ Lapsoss.configure do |config|
 end
 ```
 
+### Pipeline & Sampling (optional)
+
+```ruby
+Lapsoss.configure do |config|
+  # Build a middleware pipeline for every event
+  config.configure_pipeline do |pipeline|
+    pipeline.sample(rate: 0.1) # Drop 90% of events
+
+    pipeline.enhance_user_context(
+      provider: ->(event, _) { current_user&.slice(:id, :email) },
+      privacy_mode: true # keep only ids
+    )
+  end
+end
+```
+
 ### Filtering Errors
 
-You decide what errors to track. Lapsoss doesn't make assumptions:
+You decide what errors to track. Lapsoss doesn't make assumptions.
+
+**Execution order:** `exclusion_filter` runs first, then `before_send`.
 
 ```ruby
 Lapsoss.configure do |config|
@@ -351,6 +449,30 @@ Rails.application.config.filter_parameters += [:password, :token]
 # Lapsoss automatically uses these filters - no additional configuration needed!
 ```
 
+Additional controls:
+
+```ruby
+Lapsoss.configure do |config|
+  config.scrub_fields = %w[credit_card ssn api_key]
+  config.scrub_all = true                        # Mask everything by default
+  config.whitelist_fields = %w[user_id request_id] # Keep these fields as-is
+  config.randomize_scrub_length = true           # Avoid fixed "[FILTERED]" marker
+end
+```
+
+### Error Handler Hook
+
+Get a callback when an adapter fails to deliver:
+
+```ruby
+Lapsoss.configure do |config|
+  config.error_handler = lambda do |adapter, event, error|
+    Rails.logger.error("Delivery failed for #{adapter.name}: #{error.message}")
+    Rails.logger.error(event.to_h) if Rails.env.development?
+  end
+end
+```
+
 ### Custom Fingerprinting
 
 Control how errors are grouped:

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

@@ -12,8 +12,8 @@ module Lapsoss
         extend ActiveSupport::Concern
 
         included do
-          class_attribute :api_endpoint, instance_writer: false
-          class_attribute :api_path, default: "/", instance_writer: false
+          # Instance-level endpoint configuration for adapter isolation
+          attr_reader :api_endpoint, :api_path
 
           # Memoized git info using AS
           mattr_accessor :git_info_cache, default: {}
@@ -39,7 +39,7 @@ module Lapsoss
             handle_response(response)
           end
         rescue => error
-          handle_delivery_error(error)
+          handle_delivery_error(error, event)
         end
 
         # Common headers for all adapters
@@ -101,7 +101,7 @@ module Lapsoss
           raise DeliveryError.new("Client error: #{message}", response: response)
         end
 
-        def handle_delivery_error(error)
+        def handle_delivery_error(error, event = nil)
           ActiveSupport::Notifications.instrument("error.lapsoss",
             adapter: self.class.name,
             error: error.class.name,
@@ -109,10 +109,22 @@ module Lapsoss
           )
 
           Lapsoss.configuration.logger&.error("[#{self.class.name}] Delivery failed: #{error.message}")
-          Lapsoss.configuration.error_handler&.call(error)
+          Lapsoss.call_error_handler(adapter: self, event: event, error: error)
+          mark_error_handled(error)
 
-          raise error if error.is_a?(DeliveryError)
-          raise DeliveryError.new("Delivery failed: #{error.message}", cause: error)
+          if error.is_a?(DeliveryError)
+            raise error
+          else
+            delivery_error = DeliveryError.new("Delivery failed: #{error.message}", cause: error)
+            mark_error_handled(delivery_error)
+            raise delivery_error
+          end
+        end
+
+        def mark_error_handled(error)
+          error.instance_variable_set(:@lapsoss_error_handled, true)
+        rescue StandardError
+          # If setting the flag fails, we still continue
         end
 
         private

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

@@ -44,6 +44,16 @@ module Lapsoss
             error: "error",
             fatal: "error",
             critical: "error"
+          }.with_indifferent_access,
+
+          openobserve: {
+            debug: "DEBUG",
+            info: "INFO",
+            warning: "WARN",
+            warn: "WARN",
+            error: "ERROR",
+            fatal: "FATAL",
+            critical: "FATAL"
           }.with_indifferent_access
         }.freeze
 

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/object/blank"
+
+module Lapsoss
+  module Adapters
+    module Concerns
+      # Shared stacktrace building logic for adapters
+      # Provides consistent frame formatting across Sentry, OpenObserve, OTLP, etc.
+      module StacktraceBuilder
+        extend ActiveSupport::Concern
+
+        # Build frames from event backtrace
+        # @param event [Lapsoss::Event] The event with backtrace_frames
+        # @param reverse [Boolean] Reverse frame order (Sentry expects oldest-to-newest)
+        # @return [Array<Hash>] Array of formatted frame hashes
+        def build_frames(event, reverse: false)
+          return [] unless event.has_backtrace?
+
+          frames = event.backtrace_frames.map { |frame| build_frame(frame) }
+          reverse ? frames.reverse : frames
+        end
+
+        # Build a single frame hash from a BacktraceFrame
+        # @param frame [Lapsoss::BacktraceFrame] The frame to format
+        # @return [Hash] Formatted frame hash
+        def build_frame(frame)
+          frame_hash = {
+            filename: frame.filename,
+            abs_path: frame.absolute_path || frame.filename,
+            function: frame.method_name || frame.function,
+            lineno: frame.line_number,
+            in_app: frame.in_app
+          }
+
+          add_code_context(frame_hash, frame) if frame.code_context.present?
+
+          frame_hash.compact
+        end
+
+        # Build raw stacktrace string for logging/simple formats
+        # @param event [Lapsoss::Event] The event with backtrace_frames
+        # @return [Array<String>] Array of formatted frame strings
+        def build_raw_stacktrace(event)
+          return [] unless event.has_backtrace?
+
+          event.backtrace_frames.map do |frame|
+            "#{frame.absolute_path || frame.filename}:#{frame.line_number} in `#{frame.method_name}`"
+          end
+        end
+
+        # Build stacktrace as single string (for OTLP exception.stacktrace)
+        # @param event [Lapsoss::Event] The event with backtrace_frames
+        # @return [String] Newline-separated stacktrace
+        def build_stacktrace_string(event)
+          build_raw_stacktrace(event).join("\n")
+        end
+
+        private
+
+        def add_code_context(frame_hash, frame)
+          frame_hash[:pre_context] = frame.code_context[:pre_context]
+          frame_hash[:context_line] = frame.code_context[:context_line]
+          frame_hash[:post_context] = frame.code_context[:post_context]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "securerandom"
+
+module Lapsoss
+  module Adapters
+    module Concerns
+      # Trace context utilities for OTLP and distributed tracing
+      # Provides trace/span ID generation and timestamp formatting
+      module TraceContext
+        extend ActiveSupport::Concern
+
+        # Generate a W3C Trace Context compliant trace ID (32 hex chars = 128 bits)
+        # @return [String] 32 character hex string
+        def generate_trace_id
+          SecureRandom.hex(16)
+        end
+
+        # Generate a W3C Trace Context compliant span ID (16 hex chars = 64 bits)
+        # @return [String] 16 character hex string
+        def generate_span_id
+          SecureRandom.hex(8)
+        end
+
+        # Convert time to nanoseconds since Unix epoch (OTLP format)
+        # @param time [Time] The time to convert
+        # @return [Integer] Nanoseconds since Unix epoch
+        def timestamp_nanos(time)
+          time ||= Time.current
+          (time.to_f * 1_000_000_000).to_i
+        end
+
+        # Convert time to microseconds since Unix epoch (OpenObserve format)
+        # @param time [Time] The time to convert
+        # @return [Integer] Microseconds since Unix epoch
+        def timestamp_micros(time)
+          time ||= Time.current
+          (time.to_f * 1_000_000).to_i
+        end
+
+        # Convert time to milliseconds since Unix epoch
+        # @param time [Time] The time to convert
+        # @return [Integer] Milliseconds since Unix epoch
+        def timestamp_millis(time)
+          time ||= Time.current
+          (time.to_f * 1_000).to_i
+        end
+      end
+    end
+  end
+end

data/lib/lapsoss/adapters/openobserve_adapter.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+require "base64"
+
+module Lapsoss
+  module Adapters
+    # OpenObserve adapter - sends errors as structured JSON logs
+    # OpenObserve is an observability platform that accepts logs via simple JSON API
+    # Docs: https://openobserve.ai/docs/ingestion/
+    class OpenobserveAdapter < Base
+      include Concerns::LevelMapping
+      include Concerns::HttpDelivery
+
+      self.level_mapping_type = :openobserve
+
+      DEFAULT_STREAM = "errors"
+      DEFAULT_ORG = "default"
+
+      def initialize(name, settings = {})
+        super
+
+        @endpoint = settings[:endpoint].presence || ENV["OPENOBSERVE_ENDPOINT"]
+        @username = settings[:username].presence || ENV["OPENOBSERVE_USERNAME"]
+        @password = settings[:password].presence || ENV["OPENOBSERVE_PASSWORD"]
+        @org = settings[:org].presence || ENV["OPENOBSERVE_ORG"] || DEFAULT_ORG
+        @stream = settings[:stream].presence || ENV["OPENOBSERVE_STREAM"] || DEFAULT_STREAM
+
+        if @endpoint.blank? || @username.blank? || @password.blank?
+          Lapsoss.configuration.logger&.warn "[Lapsoss::OpenobserveAdapter] Missing endpoint, username or password - adapter disabled"
+          @enabled = false
+          return
+        end
+
+        setup_endpoint
+      end
+
+      def capture(event)
+        deliver(event.scrubbed)
+      end
+
+      def capabilities
+        super.merge(
+          breadcrumbs: false,
+          code_context: true,
+          data_scrubbing: true
+        )
+      end
+
+      private
+
+      def setup_endpoint
+        uri = URI.parse(@endpoint)
+        @api_endpoint = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+        @api_path = "/api/#{@org}/#{@stream}/_json"
+      end
+
+      def build_payload(event)
+        # OpenObserve expects JSON array of log entries
+        [ build_log_entry(event) ]
+      end
+
+      def build_log_entry(event)
+        entry = {
+          _timestamp: timestamp_microseconds(event.timestamp),
+          level: map_level(event.level),
+          logger: "lapsoss",
+          environment: event.environment.presence || "production",
+          service: @settings[:service_name].presence || "rails"
+        }
+
+        case event.type
+        when :exception
+          entry.merge!(build_exception_entry(event))
+        when :message
+          entry[:message] = event.message
+        else
+          entry[:message] = event.message || "Unknown event"
+        end
+
+        # Add optional context
+        entry[:user] = event.user_context if event.user_context.present?
+        entry[:tags] = event.tags if event.tags.present?
+        entry[:extra] = event.extra if event.extra.present?
+        entry[:request] = event.request_context if event.request_context.present?
+        entry[:transaction] = event.transaction if event.transaction.present?
+        entry[:fingerprint] = event.fingerprint if event.fingerprint.present?
+
+        entry.compact_blank
+      end
+
+      def build_exception_entry(event)
+        entry = {
+          message: "#{event.exception_type}: #{event.exception_message}",
+          exception_type: event.exception_type,
+          exception_message: event.exception_message
+        }
+
+        if event.has_backtrace?
+          entry[:stacktrace] = format_stacktrace(event)
+          entry[:stacktrace_raw] = event.backtrace_frames.map do |frame|
+            "#{frame.absolute_path || frame.filename}:#{frame.line_number} in `#{frame.method_name}`"
+          end
+        end
+
+        entry
+      end
+
+      def format_stacktrace(event)
+        event.backtrace_frames.map do |frame|
+          frame_entry = {
+            filename: frame.filename,
+            abs_path: frame.absolute_path || frame.filename,
+            function: frame.method_name || frame.function,
+            lineno: frame.line_number,
+            in_app: frame.in_app
+          }
+
+          if frame.code_context.present?
+            frame_entry[:context_line] = frame.code_context[:context_line]
+            frame_entry[:pre_context] = frame.code_context[:pre_context]
+            frame_entry[:post_context] = frame.code_context[:post_context]
+          end
+
+          frame_entry.compact
+        end
+      end
+
+      def timestamp_microseconds(time)
+        # OpenObserve expects _timestamp in microseconds
+        (time.to_f * 1_000_000).to_i
+      end
+
+      def serialize_payload(payload)
+        json = ActiveSupport::JSON.encode(payload)
+
+        if json.bytesize >= compress_threshold
+          [ ActiveSupport::Gzip.compress(json), true ]
+        else
+          [ json, false ]
+        end
+      end
+
+      def compress_threshold
+        @settings[:compress_threshold] || 1024
+      end
+
+      def adapter_specific_headers
+        credentials = Base64.strict_encode64("#{@username}:#{@password}")
+        {
+          "Authorization" => "Basic #{credentials}"
+        }
+      end
+    end
+  end
+end