debugbundle 2.0.1 → 2.1.0

data/lib/debugbundle/client_event_support.rb

@@ -9,11 +9,12 @@ module DebugBundle
 
       def capture_enabled?
         ensure_current_process!
-        config.enabled? && config.configured?
+        !@closed && config.enabled? && config.configured?
       end
 
       def merge_context(context)
-        merged = @context.merge(stringify_hash(context || {}))
+        scoped = @operations.current&.fetch(:correlation) || {}
+        merged = @context.merge(scoped).merge(stringify_hash(context || {}))
         @redactor.redact_value(merged)
       end
 
@@ -46,7 +47,13 @@ module DebugBundle
         }
       end
 
-      def runtime_payload = Runtime.payload
+      def runtime_payload
+        snapshot = Runtime.payload
+        # Engine metadata belongs in the existing extensible runtime block;
+        # unknown top-level runtime keys are rejected by installed acceptors.
+        extras = snapshot.slice('engine', 'engine_version')
+        snapshot.except('engine', 'engine_version').merge('framework_extras' => extras)
+      end
 
       def exception_causes(error)
         causes = []
@@ -144,15 +151,7 @@ module DebugBundle
         { 'value' => '[REDACTED]' }
       end
 
-      def apply_before_send(event)
-        protected = protect_event(event)
-        return nil unless protected
-
-        prepared = BeforeSend.apply(protected, config.before_send)
-        prepared && protect_event(prepared)
-      end
-
-      def protect_event(event)
+      def protect_event_fields(event)
         return nil unless TelemetryPrivacy.safe_event_identity?(event, additional_fields: config.redact_fields)
 
         fields = TelemetryPrivacy.protect(

data/lib/debugbundle/client_evidence_support.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require 'debugbundle/diagnostic_budget'
+require 'debugbundle/evidence_delivery'
+require 'debugbundle/exception_evidence'
+require 'debugbundle/operation_context'
+require 'debugbundle/event_batch'
+
+module DebugBundle
+  class Client
+    module EvidenceSupport
+      def with_operation_context(kind:, name: nil, limit_ms: nil, correlation: nil)
+        ensure_current_process!
+        unless @closed
+          lease = @operations.begin_scope(kind: kind, name: name, limit_ms: limit_ms, correlation: correlation)
+        end
+        yield
+      ensure
+        @operations.end_scope(lease)
+      end
+
+      def capture_recovery(observation = nil, context: nil, **options)
+        return unless capture_enabled? && recovery_allowed?
+
+        return if observation && !options.empty?
+
+        input = EvidenceValue.options(observation || options)
+        payload = EvidenceWire.recovery(input, @operations.scope)
+        return unless payload
+
+        event = base_event('diagnostic_context', payload, merge_context(context))
+        return unless EvidenceWire.valid_optional?(event)
+
+        enqueue_event(event)
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def apply_before_send(event)
+        protected = protect_event(event)
+        return nil unless protected
+
+        prepared = BeforeSend.apply(protected, config.before_send)
+        return nil unless prepared
+
+        result = protect_event(prepared)
+        return result if prepared.equal?(protected)
+
+        result if result && BeforeSend.valid?(result)
+      end
+
+      def protect_event(event)
+        protected = protect_event_fields(event)
+        return fit_protected_event(protected) if protected && EvidenceWire.valid_optional?(protected)
+
+        legacy = EvidenceWire.without_optional(event)
+        fit_protected_event(legacy && protect_event_fields(legacy))
+      rescue StandardError
+        legacy = EvidenceWire.without_optional(event)
+        fit_protected_event(legacy && protect_event_fields(legacy))
+      end
+
+      def fit_protected_event(event)
+        return event if @transport.is_a?(Transport::FileTransport)
+
+        EventBatch.fit(event)
+      end
+
+      def initialize_evidence
+        @evidence = EvidenceDelivery.new(config.evidence_capabilities)
+        @operations = OperationContext.new
+        @diagnostics = DiagnosticBudget.new
+      end
+
+      def recovery_allowed?
+        config.capture_recovery_observations && @evidence.supports?('recovery_v1') &&
+          @capture_policy.preset != 'minimal' && @capture_policy.capture_diagnostic_context != false
+      end
+
+      def evidence_context(context)
+        return context unless @evidence.supports?('recovery_v1') || @evidence.supports?('resource_observations_v1')
+
+        reference = EvidenceWire.capture_reference(context, @operations.scope)
+        reference ? context.except('failure_ref', 'evidence_scope').merge('evidence_reference' => reference) : context
+      end
+
+      def enrich_exception(event, retained, causes, fatal:)
+        return event unless config.capture_exception_evidence && @evidence.supports?('exception_evidence_v1')
+
+        metadata = {}
+        execution = @operations.snapshot
+        metadata['execution'] = execution if execution
+        reference = EvidenceWire.reference(event.dig('context', 'evidence_reference'))
+        metadata['evidence_reference'] = reference if reference
+        maximum = (fatal ? 4096 : 32_768) - EvidenceJson.bytes(metadata) - 32
+        graph = ExceptionEvidence.from_retained(root: retained, causes: causes, fatal: fatal, budget_bytes: maximum)
+        event['payload']['exception_evidence'] = graph if graph
+        event['payload']['execution'] = execution if execution
+        event
+      rescue StandardError
+        event
+      end
+
+      def filter_evidence(event)
+        features = @evidence.features
+        features -= ['exception_evidence_v1'] unless config.capture_exception_evidence
+        EvidenceWire.supported(event, features)
+      end
+
+      def reserve_diagnostic_locked(event, bytes)
+        event['event_type'] != 'diagnostic_context' ||
+          (recovery_allowed? && event.dig('payload', 'kind') == 'recovery' &&
+            @diagnostics.reserve(event['event_id'], event['payload'], bytes, now.to_f))
+      end
+
+      def reconcile_diagnostic(original, replacement)
+        @buffer_mutex.synchronize do
+          original_id = original['event_type'] == 'diagnostic_context' ? original['event_id'] : nil
+          if replacement['event_type'] == 'diagnostic_context'
+            return false unless recovery_allowed? && replacement.dig('payload', 'kind') == 'recovery'
+
+            payload = replacement['payload']
+            size = JSON.generate(replacement).bytesize
+            return original_id ? @diagnostics.replace(original_id, replacement['event_id'], payload, size,
+                                                      now.to_f) : @diagnostics.reserve(replacement['event_id'],
+                                                                                       payload, size, now.to_f)
+          end
+          @diagnostics.release([original_id]) if original_id
+          if %w[backend_exception frontend_exception].include?(replacement['event_type'])
+            reference = EvidenceWire.reference(replacement.dig('context', 'evidence_reference'))
+            if reference
+              @diagnostics.register_failure(reference, replacement['event_id'],
+                                            Time.iso8601(replacement['occurred_at']).to_f)
+            end
+          end
+          true
+        end
+      end
+
+      def release_diagnostics_locked(event, finalized = nil)
+        ids = []
+        ids << event['event_id'] if event['event_type'] == 'diagnostic_context'
+        ids << finalized['event_id'] if finalized && finalized['event_type'] == 'diagnostic_context'
+        @diagnostics.release(ids)
+      end
+
+      def downgrade_evidence_errors(batch, decision, lost)
+        return [] unless lost
+
+        decision.fetch(:terminal_errors).filter_map do |index, reason|
+          next unless reason == 'invalid_event'
+
+          original = batch.fetch(index)
+          finalized = @buffer_mutex.synchronize { @finalized_events[original['event_id']] || original }
+          next unless %w[backend_exception frontend_exception].include?(finalized['event_type'])
+
+          reduced = filter_evidence(finalized)
+          next if reduced == finalized
+
+          original if cache_finalized_event(original, reduced)
+        end
+      end
+    end
+
+    include EvidenceSupport
+  end
+end

data/lib/debugbundle/client_exception_support.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module DebugBundle
+  class Client
+    module ExceptionSupport
+      private
+
+      def capture_exception_internal(error, context:, handled:, run_before_send:)
+        return unless capture_enabled?
+        return unless preflight_capacity?(3, 'exception')
+
+        request_remote_config_poll_if_due
+
+        merged_context = evidence_context(merge_context(context))
+        payload = {
+          'name' => safe_exception_name(error),
+          'message' => safe_exception_message(error),
+          'stack' => safe_exception_stack(error),
+          'handled' => handled,
+          'request' => request_payload(merged_context['request']),
+          'response' => response_payload(merged_context['response']),
+          'runtime' => runtime_payload
+        }
+
+        causes = exception_causes(error)
+        retained = payload.slice('name', 'message', 'stack')
+        payload['message'] = payload['name'] if payload['message'].strip.empty?
+        payload['stack'] = "#{payload['name']}: #{payload['message']}" if payload['stack'].empty?
+
+        probe_data = probe_snapshot
+        payload['probe_data'] = probe_data unless probe_data.empty?
+
+        extra_context = merged_context.dup
+        extra_context['causes'] = causes unless causes.empty?
+
+        event = base_event('backend_exception', payload, extra_context)
+
+        event_payload = event.fetch('payload')
+        suppression_key = [
+          event['event_type'],
+          event_payload['name'],
+          event_payload['message'],
+          event_payload['stack']
+        ].join(':')
+        return unless @suppression.should_capture(suppression_key, now: monotonic_now)
+
+        event = enrich_exception(event, retained, causes, fatal: !run_before_send)
+        enqueue_event(event, skip_before_send: !run_before_send)
+      end
+    end
+
+    include ExceptionSupport
+  end
+end

data/lib/debugbundle/client_process_support.rb

@@ -13,19 +13,11 @@ module DebugBundle
         inherited_probes_enabled = @remote_config.probes_enabled
         # A fork inherits buffers, locks, and an unusable sender thread. Reset them
         # before touching any inherited synchronization object or captured event.
-        @buffer = []
-        @buffer_bytes = 0
-        @buffer_priority_counts = [0, 0, 0, 0]
-        @inflight_event_ids = Set.new
-        @inflight_priority_counts = [0, 0, 0, 0]
-        @event_sizes = {}
-        @pressure_drops = {}
-        @hook_bypass = Set.new
-        @finalized_events = {}
-        @buffer_mutex = Mutex.new
-        @flush_mutex = Mutex.new
+        initialize_buffer_ownership
         @probe_buffers = {}
         @context = {}
+        @operations&.clear
+        initialize_evidence
         @suppression = Suppression::Tracker.new
         @last_event_at = nil
         @retry_at = nil
@@ -41,7 +33,8 @@ module DebugBundle
         @delivery_worker = nil
         @config_worker = nil
         @owner_pid = current_pid
-        return unless config.enabled? && config.configured?
+        @closed = @retired
+        return unless !@closed && config.enabled? && config.configured?
 
         @delivery_worker = DeliveryWorker.new(
           interval: config.flush_interval,

data/lib/debugbundle/client_queue_support.rb

@@ -5,6 +5,20 @@ module DebugBundle
     module QueueSupport
       private
 
+      def initialize_buffer_ownership
+        @buffer = []
+        @buffer_bytes = 0
+        @buffer_priority_counts = [0, 0, 0, 0]
+        @inflight_event_ids = Set.new
+        @inflight_priority_counts = [0, 0, 0, 0]
+        @event_sizes = {}
+        @pressure_drops = {}
+        @hook_bypass = Set.new
+        @finalized_events = {}
+        @buffer_mutex = Mutex.new
+        @flush_mutex = Mutex.new
+      end
+
       def preflight_capacity?(priority, kind)
         @buffer_mutex.synchronize do
           full = @buffer.length >= MAX_BUFFER_SIZE || @buffer_bytes >= MAX_BUFFER_BYTES
@@ -23,7 +37,10 @@ module DebugBundle
 
         event_size = JSON.generate(event).bytesize
         admitted, buffered = @buffer_mutex.synchronize do
+          next [false, @buffer.length] unless reserve_diagnostic_locked(event, event_size)
+
           unless admit_event_locked?(event, event_size)
+            release_diagnostics_locked(event)
             record_pressure_drop_locked(event) if record_pressure
             next [false, @buffer.length]
           end
@@ -118,7 +135,8 @@ module DebugBundle
         @buffer_priority_counts[event_priority(event)] -= 1
         @inflight_priority_counts[event_priority(event)] -= 1 if @inflight_event_ids.delete?(event_id)
         @hook_bypass.delete(event_id)
-        @finalized_events.delete(event_id)
+        finalized = @finalized_events.delete(event_id)
+        release_diagnostics_locked(event, finalized)
       end
 
       def evictable_event_index(priority)
@@ -130,9 +148,13 @@ module DebugBundle
       def cache_finalized_event(event, finalized)
         # The original stays available for acknowledgement identity and retries, so
         # a distinct hook replacement owns additional bytes until removal.
+        finalized = event if finalized == event
         extra_bytes = finalized.equal?(event) ? 0 : JSON.generate(finalized).bytesize
         @buffer_mutex.synchronize do
-          while @buffer_bytes + extra_bytes > MAX_BUFFER_BYTES
+          previous = @finalized_events[event['event_id']]
+          old_extra = previous && !previous.equal?(event) ? JSON.generate(previous).bytesize : 0
+          delta = extra_bytes - old_extra
+          while @buffer_bytes + delta > MAX_BUFFER_BYTES
             index = evictable_event_index(event_priority(event))
             unless index
               record_pressure_drop_locked(event)
@@ -142,8 +164,8 @@ module DebugBundle
             remove_event_ownership_locked(removed)
             record_pressure_drop_locked(removed)
           end
-          @buffer_bytes += extra_bytes
-          @event_sizes[event['event_id']] += extra_bytes
+          @buffer_bytes += delta
+          @event_sizes[event['event_id']] += delta
           @finalized_events[event['event_id']] = finalized
         end
       end
@@ -156,11 +178,44 @@ module DebugBundle
         end
       end
 
+      def prepare_wire_batch(candidates)
+        prepared = []
+        size = EventBatch::WRAPPER_BYTES
+        limit = @transport.is_a?(Transport::FileTransport) ? nil : EventBatch::MAX_BODY_BYTES
+        candidates.each do |event|
+          finalized = finalized_event_for(event)
+          unless finalized
+            remove_buffered_events([event])
+            next
+          end
+
+          cost = EventBatch.bytes(finalized) + (prepared.empty? ? 0 : 1)
+          break if limit && size + cost > limit
+
+          prepared << [event, finalized]
+          size += cost
+        end
+        prepared
+      end
+
       def release_buffered_batch
         @buffer_mutex.synchronize do
           @inflight_event_ids.clear
           @inflight_priority_counts = [0, 0, 0, 0]
+          discard_closed_buffer_locked if @closed
+        end
+      end
+
+      def discard_closed_buffer_locked
+        # A stopped sender discards queued work. An active send keeps ownership
+        # charged until its ensure block releases the last snapshot.
+        @buffer.reject! do |event|
+          next false if @inflight_event_ids.include?(event['event_id'])
+
+          remove_event_ownership_locked(event)
+          true
         end
+        @diagnostics = DiagnosticBudget.new if @buffer.empty?
       end
 
       def buffered_batch

data/lib/debugbundle/config.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'debugbundle/evidence_wire'
+
 module DebugBundle
   class Config
     DEFAULT_ENDPOINT = 'https://api.debugbundle.com/v1/events'
@@ -40,7 +42,10 @@ module DebugBundle
                 :max_probe_entries_per_label,
                 :probe_flush_on_error,
                 :probes_poll_interval,
-                :before_send
+                :before_send,
+                :capture_exception_evidence,
+                :capture_recovery_observations,
+                :evidence_capabilities
 
     def initialize(
       project_token: nil,
@@ -63,7 +68,10 @@ module DebugBundle
       max_probe_entries_per_label: DEFAULT_MAX_PROBE_ENTRIES_PER_LABEL,
       probe_flush_on_error: DEFAULT_PROBE_FLUSH_ON_ERROR,
       probes_poll_interval: DEFAULT_PROBES_POLL_INTERVAL,
-      before_send: nil
+      before_send: nil,
+      capture_exception_evidence: true,
+      capture_recovery_observations: false,
+      evidence_capabilities: nil
     )
       @project_token = project_token
       @enabled = enabled
@@ -92,6 +100,11 @@ module DebugBundle
       @probe_flush_on_error = probe_flush_on_error
       @probes_poll_interval = normalize_positive_number(probes_poll_interval, DEFAULT_PROBES_POLL_INTERVAL)
       @before_send = before_send.respond_to?(:call) ? before_send : nil
+      @capture_exception_evidence = !false.equal?(capture_exception_evidence)
+      @capture_recovery_observations = true.equal?(capture_recovery_observations)
+      @evidence_capabilities = EvidenceWire.descriptor(EvidenceValue.options(evidence_capabilities))
+      @evidence_capabilities['features'].freeze
+      @evidence_capabilities.freeze
       freeze
     end
 

data/lib/debugbundle/diagnostic_budget.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module DebugBundle
+  # Caller holds the destination's buffer mutex. Metadata and pending serialized
+  # ownership share a 64 KiB budget; ACK/retry cannot renew an expired window.
+  class DiagnosticBudget
+    def initialize
+      @windows = {}
+      @pending = {}
+      @held = 0
+    end
+
+    def accounted_bytes = @held + @windows.values.sum { |window| window[:cost] }
+
+    def key(payload)
+      scope = payload.fetch('scope')
+      JSON.generate([payload.fetch('failure_ref'), scope.fetch('kind'), scope['operation_id'] || scope['page_id']])
+    end
+
+    def metadata_cost(scope, window) = JSON.generate([scope, window.except(:cost)]).bytesize
+
+    def prune(now)
+      @windows.delete_if { |_key, window| window[:pending].zero? && now >= window[:starts] + 300 }
+    end
+
+    def window(now)
+      { starts: now, failure_at: nil, failure_id: nil, attempts: [], observations: 0,
+        resource: false, ambiguous: false, pending: 0, cost: 0 }
+    end
+
+    def register_failure(payload, event_id, now)
+      return false unless now.is_a?(Numeric) && now.finite?
+
+      prune(now)
+      scope = key(payload)
+      previous = @windows[scope]
+      if previous && previous[:failure_id] && previous[:failure_id] != event_id
+        previous[:ambiguous] = true
+        previous[:cost] = metadata_cost(scope, previous)
+        return false
+      end
+      return false if previous.nil? && @windows.length >= 50
+
+      value = previous ? previous.dup : window(now)
+      value[:failure_id] = event_id
+      value[:failure_at] ||= now
+      store(scope, previous, value)
+    end
+
+    def store(scope, previous, value, extra = 0)
+      value[:cost] = metadata_cost(scope, value)
+      return false if accounted_bytes - (previous ? previous[:cost] : 0) + value[:cost] + extra > 65_536
+
+      @windows[scope] = value
+      !value[:ambiguous]
+    end
+
+    def reserve(event_id, payload, bytes, now)
+      return false unless valid_size?(bytes) && now.is_a?(Numeric) && now.finite? && !@pending.key?(event_id)
+
+      prune(now)
+      scope = key(payload)
+      previous = @windows[scope]
+      return false if (previous.nil? && @windows.length >= 50) || (previous && previous[:ambiguous])
+
+      value = previous ? previous.merge(attempts: previous[:attempts].dup) : window(now)
+      return false if now < value[:starts] || now > (value[:failure_at] || value[:starts]) + 300
+      return false if value[:observations] >= 20 || !admit_kind?(value, payload, now)
+
+      value[:pending] += 1
+      value[:observations] += 1
+      cost = bytes + event_id.bytesize + scope.bytesize + 64
+      return false unless store(scope, previous, value, cost)
+
+      @pending[event_id] =
+        { scope: scope, kind: payload['kind'], attempt: payload['attempt_id'], size: bytes, cost: cost }
+      @held += cost
+      true
+    end
+
+    def admit_kind?(value, payload, now)
+      if payload['kind'] == 'recovery'
+        attempt = payload['attempt_id']
+        return false if !value[:attempts].include?(attempt) && value[:attempts].length >= 5
+
+        value[:attempts] |= [attempt]
+      else
+        return false if value[:resource] || value[:failure_id] != payload['source_event_id']
+        return false unless value[:failure_at] && now <= value[:failure_at] + 30
+
+        value[:resource] = true
+      end
+      true
+    end
+
+    def replace(original_id, event_id, payload, bytes, now)
+      entry = @pending[original_id]
+      same_scope = entry && entry[:scope] == key(payload)
+      unless same_scope && entry[:kind] == payload['kind'] && entry[:attempt] == payload['attempt_id']
+        release([original_id])
+        return reserve(event_id, payload, bytes, now)
+      end
+      if event_id != original_id
+        if @pending.key?(event_id)
+          release([original_id])
+          return false
+        end
+        @pending[event_id] = @pending.delete(original_id)
+        delta = event_id.bytesize - original_id.bytesize
+        entry[:cost] += delta
+        @held += delta
+      end
+      if !adjust(event_id, bytes) || !eligible(event_id, payload)
+        release([event_id])
+        return false
+      end
+      true
+    end
+
+    def adjust(event_id, bytes)
+      entry = @pending[event_id]
+      return false unless entry && valid_size?(bytes) && accounted_bytes + bytes - entry[:size] <= 65_536
+
+      @held += bytes - entry[:size]
+      entry[:cost] += bytes - entry[:size]
+      entry[:size] = bytes
+      true
+    end
+
+    def eligible(event_id, payload)
+      entry = @pending[event_id]
+      value = @windows[key(payload)]
+      entry && entry[:scope] == key(payload) && value && !value[:ambiguous] &&
+        (payload['kind'] == 'recovery' || value[:failure_id] == payload['source_event_id'])
+    end
+
+    def release(event_ids)
+      event_ids.compact.uniq.each do |id|
+        entry = @pending.delete(id)
+        next unless entry
+
+        @held -= entry[:cost]
+        value = @windows[entry[:scope]]
+        next unless value
+
+        value[:pending] = [value[:pending] - 1, 0].max
+        value[:cost] = metadata_cost(entry[:scope], value)
+      end
+    end
+
+    def valid_size?(size) = size.is_a?(Integer) && size.between?(0, 65_536)
+  end
+end