hyperprobe-agent 1.2.27.pre.3-java

data/lib/hyperprobe/core/monitoring_engine.rb

@@ -0,0 +1,857 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'json'
+require 'monitor'
+require 'debug_inspector' if RUBY_ENGINE == 'ruby'
+require 'objspace' if RUBY_ENGINE == 'ruby'
+require_relative 'logger'
+require_relative 'evaluator'
+require_relative 'lexical_scope'
+
+module HyperProbe
+  module Core
+    class MonitoringEngine
+      DURATION_TTL_SECONDS = 60.0
+      MAX_DURATION_ENTRIES = 10_000
+      MAX_PROBES = 100
+      MAX_STACK_FRAMES = 16
+      MAX_CALLER_SCOPES = 256
+      MAX_INSPECTOR_STACK_DEPTH = 128
+      MAX_CALLER_ISEQS = 32
+      MAX_CALLER_ISEQ_BYTES = 16_384
+      ISEQ_TO_A = RubyVM::InstructionSequence.instance_method(:to_a) if RUBY_ENGINE == 'ruby'
+      ISEQ_EACH_CHILD = RubyVM::InstructionSequence.instance_method(:each_child) if RUBY_ENGINE == 'ruby'
+      ISEQ_MEMORY_SIZE = ObjectSpace.method(:memsize_of) if RUBY_ENGINE == 'ruby'
+      LOCAL_VARIABLES = Binding.instance_method(:local_variables)
+      LOCAL_GET = Binding.instance_method(:local_variable_get)
+      MODULE_NAME = Module.instance_method(:name)
+      SINGLETON_CLASS = Module.instance_method(:singleton_class?)
+      INSTANCE_METHODS = Module.instance_method(:instance_methods)
+      INSTANCE_METHOD = Module.instance_method(:instance_method)
+      METHODS = Kernel.instance_method(:methods)
+      METHOD = Kernel.instance_method(:method)
+
+      LEVEL_COLORS = {
+        'ERROR' => "\e[31m",
+        'WARN'  => "\e[33m",
+        'INFO'  => "\e[32m",
+        'DEBUG' => "\e[36m"
+      }.freeze
+      COLOR_RESET = "\e[0m"
+      COLOR_BOLD = "\e[1m"
+      COLOR_GRAY = "\e[90m"
+      COLOR_MAGENTA = "\e[35m"
+
+      attr_reader :total_hits, :total_skips, :is_suspended, :is_active
+
+      def initialize(quota_manager, safety_monitor, on_capture, custom_set_trace_id = nil)
+        @quota_manager = quota_manager
+        @safety_monitor = safety_monitor
+        @on_capture = on_capture
+        @custom_set_trace_id = custom_set_trace_id
+
+        @mutex = Monitor.new
+        @path_mutex = Monitor.new
+        @active_locations = {} # [resolved_file_path, line] => Array<ActiveProbeContext>
+        @probe_map = {}        # probe_id => Probe
+        @instrumented_files = Set.new
+        @path_cache = {}
+        @caller_locals_cache = ObjectSpace::WeakMap.new if RUBY_ENGINE == 'ruby'
+        @duration_starts = {}  # [probe_id, correlation_id] => [start_time_monotonic, created_at_time]
+        @next_duration_cleanup = monotonic_time + DURATION_TTL_SECONDS
+
+        @global_config = {}
+        @safe_evaluation = Evaluator.safe_evaluation_enabled?
+        @total_hits = 0
+        @total_skips = 0
+        @is_suspended = false
+        @is_active = false
+        @closed = false
+        @owner_pid = Process.pid
+        @generation = -1
+
+        @log = Logger.get_logger('hyperprobe:inspector')
+        @targeted_tracepoints = {} # location_key => TracePoint instance
+        # JRuby's compiled LINE site is activated by CALL/RETURN interest.
+        # Share one empty activation hook rather than adding CALL to every probe.
+        @jruby_call_hook = TracePoint.new(:call) {} if RUBY_PLATFORM.include?('java')
+        @stdout_queue = SizedQueue.new(100)
+        @stdout_thread = Thread.new do
+          loop { $stdout.write(@stdout_queue.pop) }
+        rescue Exception
+          # A broken or blocked output stream must only affect the agent worker.
+        end
+        @stdout_thread.name = 'hyperprobe-stdout'
+      end
+
+      def set_global_config(config)
+        @mutex.synchronize do
+          @global_config = (config || {}).dup
+          disabled = @global_config.fetch(:disable_safe_evaluation) { @global_config['disable_safe_evaluation'] }
+          @safe_evaluation = Evaluator.safe_evaluation_enabled?(disabled)
+        end
+      end
+
+      def set_probes(probes, generation: nil)
+        @mutex.synchronize do
+          return if @closed
+          return if generation && generation <= @generation
+          @generation = generation if generation
+
+          new_active_locations = {}
+          new_probe_map = {}
+          new_instrumented_files = Set.new
+
+          Array(probes).first(MAX_PROBES).each do |probe|
+            probe_id = probe.respond_to?(:id) ? probe.id : probe[:id]
+            next unless probe_id
+
+            new_probe_map[probe_id] = probe
+
+            runtime_loc = probe.respond_to?(:runtime_location) ? probe.runtime_location : probe[:runtime_location]
+            runtime_line = (probe.respond_to?(:runtime_line) ? probe.runtime_line : probe[:runtime_line]).to_i
+
+            resolved_path = resolve_filepath(runtime_loc)
+            primary_key = [resolved_path, runtime_line]
+
+            new_active_locations[primary_key] ||= []
+            probe_type = probe.respond_to?(:type) ? probe.type : probe[:type]
+            local_names = nil
+            if probe_type_to_i(probe_type) == 1
+              previous = @active_locations[primary_key]&.find { |ctx| ctx[:probe].equal?(probe) && !ctx[:is_secondary] }
+              local_names = previous ? previous[:local_names] : LexicalScope.locals_for(resolved_path, runtime_line)
+            end
+            new_active_locations[primary_key] << { probe: probe, is_secondary: false, local_names: local_names }
+            new_instrumented_files.add(resolved_path)
+
+            # Duration secondary location
+            is_duration = probe_type == 5 || probe_type == :PROBE_TYPE_DURATION
+            if is_duration
+              sec_line = (probe.respond_to?(:secondary_runtime_line) ? probe.secondary_runtime_line : probe[:secondary_runtime_line]).to_i
+              if sec_line.positive?
+                sec_loc = probe.respond_to?(:secondary_runtime_location) ? probe.secondary_runtime_location : probe[:secondary_runtime_location]
+                sec_loc = runtime_loc if sec_loc.nil? || sec_loc.empty?
+                resolved_sec_path = resolve_filepath(sec_loc)
+                secondary_key = [resolved_sec_path, sec_line]
+
+                new_active_locations[secondary_key] ||= []
+                new_active_locations[secondary_key] << { probe: probe, is_secondary: true }
+                new_instrumented_files.add(resolved_sec_path)
+              end
+            end
+          end
+
+          @active_locations = new_active_locations
+          @probe_map = new_probe_map
+          @instrumented_files = new_instrumented_files
+          @duration_starts.delete_if { |(id, _), _entry| !new_probe_map.key?(id) }
+
+          update_tracepoint_state_unlocked
+        end
+      end
+
+      def suspend
+        @mutex.synchronize do
+          return if @closed || @is_suspended
+
+          @is_suspended = true
+          disable_all_tracepoints_unlocked
+        end
+      end
+
+      def resume
+        @mutex.synchronize do
+          return if @closed || !@is_suspended
+
+          @is_suspended = false
+          update_tracepoint_state_unlocked
+        end
+      end
+
+      def get_stats
+        @mutex.synchronize do
+          cleanup_durations_unlocked(monotonic_time)
+          stats = { hits: @total_hits, skips: @total_skips }
+          @total_hits = 0
+          @total_skips = 0
+          stats
+        end
+      end
+
+      def close
+        @stdout_thread&.kill
+        @mutex.synchronize do
+          return if @closed
+
+          @closed = true
+          disable_all_tracepoints_unlocked
+          @active_locations.clear
+          @probe_map.clear
+          @instrumented_files.clear
+          @duration_starts.clear
+          @caller_locals_cache = nil
+        end
+      end
+
+      def after_fork
+        # The child must not acquire locks or use resources owned by parent threads.
+        @closed = true
+        @is_suspended = true
+        @targeted_tracepoints.each_value { |tp| tp.disable rescue nil }
+        @jruby_call_hook&.disable
+        @is_active = false
+      rescue Exception
+        nil
+      end
+
+      private
+
+      def update_tracepoint_state_unlocked
+        if @closed || @is_suspended || @active_locations.empty?
+          disable_all_tracepoints_unlocked
+          return
+        end
+
+        @jruby_call_hook&.enable
+
+        # 1. Remove stale tracepoints
+        active_keys = @active_locations.keys.to_set
+        @targeted_tracepoints.delete_if do |loc_key, tp|
+          unless active_keys.include?(loc_key)
+            tp.disable rescue nil
+            true
+          end
+        end
+
+        # 2. Setup or enable targeted tracepoint for each active location
+        @active_locations.each_key do |loc_key|
+          next if @targeted_tracepoints.key?(loc_key)
+
+          enable_location_tracepoint_unlocked(loc_key)
+        end
+
+        @is_active = !@targeted_tracepoints.empty?
+      end
+
+      def create_tracepoint_for_location(loc_key, resolved_path, lineno)
+        TracePoint.new(:line) do |t|
+          next if @is_suspended || @closed || @owner_pid != Process.pid
+          # Fast integer check first to minimize overhead on uninstrumented lines
+          next unless t.lineno == lineno
+
+          contexts = nil
+          # Never wait for installation or shutdown on an application thread.
+          next unless @mutex.try_enter
+          begin
+            # Installation resolves symlinks; never resolve filesystem paths here.
+            next unless t.path == resolved_path || @path_cache[t.path] == resolved_path || File.expand_path(t.path) == resolved_path
+            contexts = @active_locations[loc_key]
+            if contexts && !contexts.empty?
+              handle_hit(contexts, t.binding)
+            end
+          ensure
+            @mutex.exit
+          end
+        rescue SignalException, SystemExit
+          raise
+        rescue Exception
+          # Includes trap-context ThreadError; host termination remains untouched.
+          # This boundary never encloses application code.
+          nil
+        end
+      end
+
+      def enable_location_tracepoint_unlocked(loc_key)
+        resolved_path, lineno = loc_key
+
+        target_method = find_method_target(resolved_path, lineno)
+        targeted_enabled = false
+        tp = nil
+
+        if target_method
+          begin
+            tp = create_tracepoint_for_location(loc_key, resolved_path, lineno)
+            tp.enable(target: target_method, target_line: lineno)
+            targeted_enabled = true
+          rescue ArgumentError, StandardError
+            # Target option not accepted by interpreter or line is outside method instructions.
+            # Must discard and disable this TracePoint because CRuby does not allow un-targeted
+            # re-enable on a TracePoint instance once target has been attempted.
+            tp&.disable rescue nil
+            tp = nil
+            targeted_enabled = false
+          end
+        end
+
+        unless targeted_enabled
+          begin
+            tp = create_tracepoint_for_location(loc_key, resolved_path, lineno)
+            tp.enable
+          rescue StandardError
+            # TracePoint enable error
+            tp = nil
+          end
+        end
+
+        @targeted_tracepoints[loc_key] = tp if tp
+      end
+
+      def disable_all_tracepoints_unlocked
+        @jruby_call_hook&.disable
+        @targeted_tracepoints.each_value do |tp|
+          tp.disable rescue nil
+        end
+        @targeted_tracepoints.clear
+        @is_active = false
+      end
+
+      def method_line_range(m)
+        return nil unless defined?(RubyVM::InstructionSequence) && RubyVM::InstructionSequence.respond_to?(:of)
+
+        iseq = RubyVM::InstructionSequence.of(m) rescue nil
+        return nil unless iseq
+
+        data = iseq.to_a[4] rescue nil
+        if data.is_a?(Hash) && data[:code_location]
+          loc = data[:code_location]
+          return (loc[0]..loc[2]) if loc.is_a?(Array) && loc.length >= 3
+        end
+
+        lines = []
+        collect_lines = ->(seq) {
+          (seq.trace_points rescue []).each { |tp_info| lines << tp_info[0] }
+          (seq.each_child rescue []).each { |child| collect_lines.call(child) }
+        }
+        collect_lines.call(iseq)
+        return (lines.min..lines.max) unless lines.empty?
+
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def find_method_target(file_path, line_number)
+        return nil unless defined?(RubyVM::InstructionSequence)
+        best_match = nil
+        best_line = 0
+        deadline = monotonic_time + 0.05
+
+        ObjectSpace.each_object(Module) do |mod|
+          break if monotonic_time >= deadline
+          next if SINGLETON_CLASS.bind(mod).call || MODULE_NAME.bind(mod).call.nil?
+
+          [:instance_methods, :methods].each do |mtype|
+            implementation = mtype == :instance_methods ? INSTANCE_METHODS : METHODS
+            methods_list = implementation.bind(mod).call(false)
+            methods_list.each do |sym|
+              break if monotonic_time >= deadline
+              implementation = mtype == :instance_methods ? INSTANCE_METHOD : METHOD
+              m = implementation.bind(mod).call(sym) rescue nil
+              next unless m
+
+              loc = m.source_location
+              next unless loc
+
+              m_file = loc[0]
+              m_line = loc[1]
+
+              next unless m_line <= line_number && m_line > best_line
+              next unless m_file == file_path || @path_cache[m_file] == file_path || File.expand_path(m_file) == file_path
+
+              range = method_line_range(m)
+              if range
+                next unless range.cover?(line_number)
+              end
+
+              best_match = m
+              best_line = m_line
+            end
+          end
+        end
+
+        best_match
+      rescue StandardError
+        nil
+      end
+
+      def resolve_filepath(runtime_location)
+        return '' if runtime_location.nil? || runtime_location.empty?
+
+        cached = @path_mutex.synchronize { @path_cache[runtime_location] }
+        return cached if cached
+
+        if File.exist?(runtime_location)
+          resolved = File.realpath(runtime_location) rescue File.expand_path(runtime_location)
+          @path_mutex.synchronize { @path_cache[runtime_location] = resolved }
+          return resolved
+        end
+
+        cwd = Dir.pwd
+        parts = runtime_location.tr('\\', '/').split('/').reject(&:empty?)
+        (0...parts.length).each do |i|
+          suffix = File.join(*parts[i..])
+          attempt = File.expand_path(suffix, cwd)
+          if File.exist?(attempt)
+            resolved = File.realpath(attempt) rescue attempt
+            @path_mutex.synchronize { @path_cache[runtime_location] = resolved }
+            return resolved
+          end
+        end
+
+        fallback = File.expand_path(runtime_location, cwd)
+        @path_mutex.synchronize { @path_cache[runtime_location] = fallback }
+        fallback
+      end
+
+      def handle_hit(contexts, binding_ctx)
+        start_time = monotonic_time
+        begin
+          contexts.each do |ctx|
+            probe = ctx[:probe]
+            is_secondary = ctx[:is_secondary]
+            process_single_probe_hit(probe, binding_ctx, is_secondary, ctx[:local_names])
+          rescue SignalException, SystemExit
+            raise
+          rescue Exception
+            # One broken probe must not prevent another probe or the host line.
+            next
+          end
+        rescue SignalException, SystemExit
+          raise
+        rescue Exception
+          nil
+        ensure
+          elapsed_ms = (monotonic_time - start_time) * 1000.0
+          @safety_monitor.report_pause_duration(elapsed_ms) rescue nil
+        end
+      end
+
+      def process_single_probe_hit(probe, binding_ctx, is_secondary, local_names = nil)
+        probe_id = probe.respond_to?(:id) ? probe.id : probe[:id]
+        probe_type = probe.respond_to?(:type) ? probe.type : probe[:type]
+        probe_type_num = probe_type.is_a?(Integer) ? probe_type : probe_type_to_i(probe_type)
+
+        # 1. Rate-limiting admission check
+        unless probe_type_num == 5 || @quota_manager.can_evaluate?
+          @mutex.synchronize { @total_skips += 1 }
+          return
+        end
+
+        # 2. Evaluate Condition (if any)
+        condition = probe.respond_to?(:condition) ? probe.condition : probe[:condition]
+        if condition && !condition.empty?
+          begin
+            passed = Evaluator.eval_condition(condition, binding_ctx, safe: @safe_evaluation)
+            return unless passed
+          rescue StandardError, ScriptError, SecurityError => e
+            report_error(probe_id, "Condition evaluation failed: #{e.class.name}: #{e.message}")
+            return
+          end
+        end
+
+        # 3. Dispatch to Probe Type Handler
+        case probe_type_num
+        when 1 # SNAPSHOT
+          handle_snapshot(probe, binding_ctx, local_names)
+        when 2 # LOG
+          handle_log(probe, binding_ctx)
+        when 3 # COUNTER
+          handle_counter(probe, binding_ctx)
+        when 4 # METRIC
+          handle_metric(probe, binding_ctx)
+        when 5 # DURATION
+          handle_duration(probe, binding_ctx, is_secondary)
+        end
+      end
+
+      def handle_snapshot(probe, binding_ctx, local_names = nil)
+        probe_id = probe.respond_to?(:id) ? probe.id : probe[:id]
+
+        max_depth = get_probe_positive_int(probe, :max_object_depth, 3)
+        max_array_length = get_probe_positive_int(probe, :max_array_length, 3)
+        max_object_properties = get_probe_positive_int(probe, :max_object_properties, 50)
+        max_string_length = get_probe_positive_int(probe, :max_string_length, 1024)
+        stack_frame_depth = [get_probe_positive_int(probe, :stack_frame_depth, 3), MAX_STACK_FRAMES].min
+        redact_keys = @global_config[:redact_keys] || @global_config['redact_keys']
+        redact_values = @global_config[:redact_values] || @global_config['redact_values']
+
+        serializer = Serializer.new(
+          max_depth: max_depth,
+          max_array_length: max_array_length,
+          max_object_properties: max_object_properties,
+          max_string_length: max_string_length,
+          redact_keys: redact_keys,
+          redact_values: redact_values
+        )
+
+        visited = {}
+
+        # 1. Watch Expressions
+        watch_expressions = get_probe_opt(probe, :watch_expressions) || []
+        serialized_watches = {}
+        if watch_expressions && !watch_expressions.empty?
+          raw_watches = Evaluator.evaluate_watches(watch_expressions.to_a, binding_ctx, safe: @safe_evaluation)
+          raw_watches.each do |expr, val|
+            watch_path = "watch[#{JSON.generate(expr)}]"
+            serialized_watches[expr] = serializer.serialize(val, watch_path, 0, visited)
+          end
+        end
+
+        # 2. Unified Stack Frames & Multi-Frame Local Variables Extraction
+        stack_frames, captured_vars = extract_stack_and_variables(
+          probe,
+          binding_ctx,
+          stack_frame_depth,
+          serializer,
+          visited,
+          local_names
+        )
+
+        event = build_base_event(probe_id)
+        event[:stack_frames] = stack_frames
+        event[:captured_vars_json] = Serializer.safe_dump_json(captured_vars)
+        event[:watch_results_json] = Serializer.safe_dump_json(serialized_watches)
+
+        emit_event(probe, event)
+      rescue StandardError, ScriptError, SecurityError => e
+        report_error(probe_id, "Snapshot capture failed: #{e.class.name}: #{e.message}")
+      ensure
+        serializer&.finish_capture
+      end
+
+      def handle_log(probe, binding_ctx)
+        probe_id = probe.respond_to?(:id) ? probe.id : probe[:id]
+        template = get_probe_opt(probe, :template) || ''
+        max_string_length = get_probe_positive_int(probe, :max_string_length, 1024)
+        redact_values = @global_config[:redact_values] || @global_config['redact_values']
+
+        evaluated = Evaluator.evaluate_log_template(template, binding_ctx, safe: @safe_evaluation)
+
+        # Redact values
+        if redact_values && !redact_values.empty?
+          regex = Serializer.new(redact_values: redact_values).send(:compile_regex, redact_values)
+          evaluated = evaluated.gsub(regex, '[REDACTED Value]') if regex
+        end
+
+        # Truncate string
+        if evaluated.length > max_string_length
+          head = evaluated[0...max_string_length]
+          truncated_head = head.sub(/\b\w*$/, '').rstrip
+          truncated_head = head if truncated_head.empty?
+          evaluated = "#{truncated_head}... [Truncated: +#{evaluated.length - max_string_length} more chars]"
+        end
+
+        # Stdout logging if configured
+        should_log_stdout = get_probe_opt(probe, :should_log_to_stdout)
+        if should_log_stdout
+          log_level = (get_probe_opt(probe, :log_level) || 'INFO').to_s.upcase
+          color = LEVEL_COLORS[log_level] || "\e[37m"
+          timestamp = Time.now.utc.iso8601(3)
+          out_line = "#{COLOR_GRAY}[#{timestamp}]#{COLOR_RESET} " \
+                     "#{COLOR_BOLD}#{color}[#{log_level}]#{COLOR_RESET} " \
+                     "#{COLOR_BOLD}#{COLOR_MAGENTA}[HyperProbe LOG]#{COLOR_RESET} " \
+                     "#{evaluated}\n"
+          @stdout_queue.push(out_line, true) rescue nil
+        end
+
+        event = build_base_event(probe_id)
+        event[:evaluated_log] = evaluated
+        emit_event(probe, event)
+      rescue StandardError, ScriptError, SecurityError => e
+        report_error(probe_id, "Log evaluation failed: #{e.class.name}: #{e.message}")
+      end
+
+      def handle_counter(probe, _binding_ctx)
+        probe_id = probe.respond_to?(:id) ? probe.id : probe[:id]
+        event = build_base_event(probe_id)
+        event[:metric_value] = 1.0
+        emit_event(probe, event)
+      end
+
+      def handle_metric(probe, binding_ctx)
+        probe_id = probe.respond_to?(:id) ? probe.id : probe[:id]
+        metric_expr = get_probe_opt(probe, :metric_expression)
+        return if metric_expr.nil? || metric_expr.empty?
+
+        begin
+          val = Evaluator.evaluate_metric(metric_expr, binding_ctx, safe: @safe_evaluation)
+        rescue StandardError, ScriptError, SecurityError => e
+          report_error(probe_id, "Metric evaluation failed: #{e.class.name}: #{e.message}")
+          return
+        end
+
+        event = build_base_event(probe_id)
+        if val
+          event[:metric_value] = val
+        else
+          event[:capture_error] = 'Metric evaluation failed: expression must return a finite number'
+        end
+        emit_event(probe, event)
+      end
+
+      def handle_duration(probe, binding_ctx, is_secondary)
+        probe_id = probe.respond_to?(:id) ? probe.id : probe[:id]
+        corr_expr = get_probe_opt(probe, :correlation_expression)
+
+        corr_id = nil
+        begin
+          corr_id = Evaluator.evaluate_correlation(corr_expr, binding_ctx, safe: @safe_evaluation)
+        rescue StandardError, ScriptError, SecurityError => e
+          report_error(probe_id, "Duration correlation failed: #{e.message}")
+          return
+        end
+
+        dur_key = [probe_id, corr_id]
+
+        if !is_secondary
+          now_mono = monotonic_time
+          @mutex.synchronize do
+            cleanup_durations_unlocked(now_mono)
+            if @duration_starts.size >= MAX_DURATION_ENTRIES
+              # Evict oldest entry to prevent unbounded memory growth
+              @duration_starts.shift
+            end
+            @duration_starts[dur_key] = [now_mono, now_mono]
+          end
+        else
+          now_mono = monotonic_time
+          start_entry = nil
+          @mutex.synchronize do
+            cleanup_durations_unlocked(now_mono)
+            start_entry = @duration_starts.delete(dur_key)
+          end
+          return unless start_entry
+          unless @quota_manager.can_evaluate?
+            @mutex.synchronize { @total_skips += 1 }
+            return
+          end
+
+          duration_ms = (now_mono - start_entry[0]) * 1000.0
+          event = build_base_event(probe_id)
+          event[:metric_value] = duration_ms
+          emit_event(probe, event)
+        end
+      end
+
+      def build_base_event(probe_id)
+        event = {
+          probe_id: probe_id,
+          timestamp_ms: (Time.now.to_f * 1000).to_i,
+          stack_frames: [],
+          captured_vars_json: '',
+          watch_results_json: '',
+          evaluated_log: '',
+          metric_value: 0.0,
+          capture_error: '',
+          trace_id: nil
+        }
+
+        probe = @probe_map[probe_id]
+        if probe && get_probe_opt(probe, :should_capture_trace_id)
+          trace_id = TraceExtractor.extract_trace_context(@custom_set_trace_id)
+          event[:trace_id] = trace_id if trace_id && !trace_id.empty?
+        end
+
+        event
+      end
+
+      def emit_event(_probe, event)
+        @mutex.synchronize { @total_hits += 1 }
+        @on_capture.call(event)
+      end
+
+      def report_error(probe_id, error_message)
+        event = build_base_event(probe_id)
+        event[:capture_error] = error_message
+        emit_event(nil, event)
+      end
+
+      def extract_stack_and_variables(probe, binding_ctx, stack_frame_depth, serializer, visited, local_names)
+        stack_frames = []
+        captured_vars = []
+
+        snapshot_frames(binding_ctx, local_names, stack_frame_depth).each_with_index do |(loc, current_b, frame_local_names), frame_idx|
+
+          func = loc&.label || loc&.base_label || '(anonymous)'
+          file = loc ? (loc.absolute_path || loc.path || 'unknown') : 'unknown'
+          line_no = loc&.lineno || 0
+
+          # If frame_idx == 0 and location is unpopulated, fallback to probe location
+          if frame_idx == 0 && (file == 'unknown' || line_no == 0)
+            runtime_loc = probe.respond_to?(:runtime_location) ? probe.runtime_location : probe[:runtime_location]
+            line_no = (probe.respond_to?(:runtime_line) ? probe.runtime_line : probe[:runtime_line]).to_i
+            file = runtime_loc
+          end
+
+          stack_frames << {
+            function_name: func,
+            file_name: file,
+            line_number: line_no,
+            column_number: 0
+          }
+
+          locals_hash = {}
+          closure_hash = {}
+          if current_b
+            capture_closures = get_probe_opt(probe, :capture_closures)
+            capture_closures = @global_config[:capture_closures] if capture_closures.nil?
+            LOCAL_VARIABLES.bind(current_b).call.first(128).each do |var_sym|
+              is_local = frame_local_names && frame_local_names.include?(var_sym)
+              next unless is_local || capture_closures == true
+              var_name = var_sym.to_s
+
+              begin
+                target = is_local ? locals_hash : closure_hash
+                target[var_name] = LOCAL_GET.bind(current_b).call(var_sym)
+              rescue StandardError, ScriptError => e
+                locals_hash[var_name] = "[Error accessing variable: #{e.message}]"
+              end
+            end
+          end
+
+          serialized_locals = locals_hash.empty? ? {} : serializer.serialize(locals_hash, "frame[#{frame_idx}].scopes[0]", 0, visited)
+
+          captured_vars << [
+            {
+              'type' => 'local',
+              'name' => 'Local',
+              'vars' => serialized_locals
+            }
+          ]
+          unless closure_hash.empty?
+            captured_vars.last << {
+              'type' => 'closure', 'name' => 'Closure',
+              'vars' => serializer.serialize(closure_hash, "frame[#{frame_idx}].scopes[1]", 0, visited)
+            }
+          end
+        end
+
+        [stack_frames, captured_vars]
+      end
+
+      def snapshot_frames(binding_ctx, local_names, depth)
+        return [] unless depth.positive?
+
+        collect = proc do |locations, inspector|
+          frames = []
+          locations.first(50).each_with_index do |loc, index|
+            path = loc.path || ''
+            next if path.empty? || path.include?('hyperprobe/') || path.include?('<internal:') ||
+                    path.include?('org/jruby/') || path.include?('org.jruby.') ||
+                    path.include?('java/lang/') || path.include?('sun/reflect') || path.include?('jdk/internal')
+
+            current_b = nil
+            names = nil
+            if frames.empty?
+              current_b = binding_ctx
+              names = local_names
+            elsif inspector
+              begin
+                # Keep the inspector's original index, including native frames.
+                current_b = inspector.frame_binding(index)
+                iseq = inspector.frame_iseq(index) if current_b
+                names = caller_local_names(iseq) if iseq
+                current_b = nil unless names
+              rescue StandardError, ScriptError, SecurityError
+                current_b = nil
+              end
+            end
+            frames << [loc, current_b, names]
+            break if frames.length >= depth
+          end
+          frames.empty? ? [[nil, binding_ctx, local_names]] : frames
+        end
+
+        scan_limit = RUBY_ENGINE == 'ruby' && depth > 1 ? MAX_INSPECTOR_STACK_DEPTH + 1 : 50
+        locations = caller_locations(0, scan_limit) || []
+        if RUBY_ENGINE == 'ruby' && depth > 1 && locations.length <= MAX_INSPECTOR_STACK_DEPTH
+          begin
+            return DebugInspector.open { |inspector| collect.call(inspector.backtrace_locations, inspector) }
+          rescue StandardError, ScriptError, SecurityError
+            # An unavailable inspector must not discard the probe-hit locals.
+          end
+        end
+        collect.call(locations, nil)
+      end
+
+      def caller_local_names(iseq)
+        return @caller_locals_cache[iseq] if @caller_locals_cache.key?(iseq)
+        @caller_locals_cache = ObjectSpace::WeakMap.new if @caller_locals_cache.size >= MAX_CALLER_SCOPES
+
+        # to_a expands nested bytecode, so reject large code trees before dumping
+        # them. These admission limits are not a hard native allocation deadline.
+        pending = [iseq]
+        count = 0
+        bytes = 0
+        until pending.empty?
+          current = pending.pop
+          count += 1
+          size_before = ISEQ_MEMORY_SIZE.call(current)
+          bytes += size_before
+          return @caller_locals_cache[iseq] = nil if count > MAX_CALLER_ISEQS || bytes > MAX_CALLER_ISEQ_BYTES
+
+          ISEQ_EACH_CHILD.bind(current).call do |child|
+            pending << child
+            return @caller_locals_cache[iseq] = nil if count + pending.length > MAX_CALLER_ISEQS
+          end
+          # Enumerating children can materialize a lazily loaded binary ISeq.
+          bytes += [0, ISEQ_MEMORY_SIZE.call(current) - size_before].max
+          return @caller_locals_cache[iseq] = nil if bytes > MAX_CALLER_ISEQ_BYTES
+        end
+
+        # The compiled local table excludes enclosing variables. Weak keys avoid
+        # retaining reloaded code; only names are cached, never live bindings.
+        data = ISEQ_TO_A.bind(iseq).call
+        names = if data[0] == 'YARVInstructionSequence/SimpleDataFormat' && data[10].is_a?(Array)
+                  data[10].grep(Symbol).first(128).freeze
+                end
+        @caller_locals_cache[iseq] = names
+      end
+
+      def get_probe_positive_int(probe, key, default_val)
+        val = get_probe_opt(probe, key)
+        return val if val.is_a?(Integer) && val >= 0
+
+        global_val = @global_config[key] || @global_config[key.to_s]
+        return global_val if global_val.is_a?(Integer) && global_val >= 0
+
+        default_val
+      end
+
+      def get_probe_opt(probe, key)
+        if probe.respond_to?(key)
+          presence = "has_#{key}?"
+          return nil if probe.respond_to?(presence) && !probe.public_send(presence)
+          probe.public_send(key)
+        elsif probe.is_a?(Hash)
+          probe.key?(key) ? probe[key] : probe[key.to_s]
+        end
+      end
+
+      def probe_type_to_i(type)
+        case type
+        when :PROBE_TYPE_SNAPSHOT, 'PROBE_TYPE_SNAPSHOT', 1 then 1
+        when :PROBE_TYPE_LOG, 'PROBE_TYPE_LOG', 2 then 2
+        when :PROBE_TYPE_COUNTER, 'PROBE_TYPE_COUNTER', 3 then 3
+        when :PROBE_TYPE_METRIC, 'PROBE_TYPE_METRIC', 4 then 4
+        when :PROBE_TYPE_DURATION, 'PROBE_TYPE_DURATION', 5 then 5
+        else 0
+        end
+      end
+
+      def cleanup_durations_unlocked(now)
+        return if now < @next_duration_cleanup && @duration_starts.size < MAX_DURATION_ENTRIES
+
+        @duration_starts.delete_if do |_key, (_start_time, created_at)|
+          now - created_at > DURATION_TTL_SECONDS
+        end
+        @next_duration_cleanup = now + DURATION_TTL_SECONDS
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end