hyperprobe-agent 1.2.27.pre.1 → 1.2.27.pre.3

data/lib/hyperprobe/core/transports/java_grpc.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'uri'
+
+begin
+  require_relative '../../jars/hyperprobe-grpc.jar'
+  JavaUtilities.get_proxy_class('co.hyperprobe.transport.GrpcTransport')
+rescue Java::JavaLang::LinkageError => e
+  raise LoadError, "Cannot load HyperProbe gRPC transport (Java 11+ required): #{e.message}"
+end
+
+module HyperProbe
+  module Core
+    module Transports
+      class JavaGrpc
+        class Error < StandardError
+          attr_reader :code
+
+          def initialize(code, message)
+            @code = code
+            super(message)
+          end
+        end
+
+        def initialize(url, service_id, keep_alive)
+          raw = url.to_s.strip
+          uri = URI.parse(raw.include?('://') ? raw : "http://#{raw}")
+          unless %w[http https].include?(uri.scheme) && uri.hostname && uri.port &&
+                 uri.userinfo.nil? && ['', '/'].include?(uri.path) && uri.query.nil? && uri.fragment.nil?
+            raise ArgumentError, 'Broker URL must be http(s)://host:port or host:port'
+          end
+
+          @client = Java::CoHyperprobeTransport::GrpcTransport.new(uri.hostname, uri.port, uri.scheme == 'https', service_id, keep_alive)
+        rescue Java::JavaLang::LinkageError => e
+          raise LoadError, "Cannot initialize HyperProbe gRPC transport: #{e.message}"
+        end
+
+        def call(method, payload, deadline)
+          bytes = payload.to_java_bytes
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise Error.new(4, 'DEADLINE_EXCEEDED') unless remaining.positive?
+
+          # Saturate before conversion to Java long; never overflow into an unlimited call.
+          nanos = [(remaining * 1_000_000_000).to_i, 9_223_372_036_854_775_807].min
+          String.from_java_bytes(@client.call(method, bytes, nanos))
+        rescue Java::CoHyperprobeTransport::GrpcTransport::RpcException => e
+          raise Error.new(e.code, e.message)
+        end
+
+        def shutdown
+          @client.shutdown
+        end
+      end
+    end
+  end
+end

data/lib/hyperprobe/lambda.rb

@@ -16,62 +16,58 @@ module HyperProbe
 
         # Ephemeral Lambda wrapper
         lambda do |event:, context:|
-          unless HyperProbe.instance
-            HyperProbe.start(options.merge(is_lambda: true))
-          end
-
-          agent = HyperProbe.instance
-          is_active = agent && !agent.agent_disabled?
-
-          if is_active
-            remaining_ms = context.respond_to?(:get_remaining_time_in_millis) ? context.get_remaining_time_in_millis : nil
-            sync_timeout_ms = options[:lambda_sync_timeout_ms] || 2000
-
-            if remaining_ms
-              dynamic_budget = (remaining_ms * 0.2).to_i
-              if dynamic_budget < 100
-                sync_timeout_ms = 0
-              else
-                sync_timeout_ms = [sync_timeout_ms, dynamic_budget].min
-              end
-            end
-
-            if sync_timeout_ms.positive?
-              begin
-                agent.force_sync(sync_timeout_ms / 1000.0)
-              rescue StandardError => e
-                warn "[HyperProbe Lambda] Failed to sync probes: #{e.message}"
+          agent = nil
+          begin
+            HyperProbe.start(options.merge(is_lambda: true)) unless HyperProbe.instance
+            agent = HyperProbe.instance
+            agent = nil if agent && agent.agent_disabled?
+            if agent
+              remaining_ms = context.respond_to?(:get_remaining_time_in_millis) ? context.get_remaining_time_in_millis : nil
+              sync_timeout_ms = options[:lambda_sync_timeout_ms] || 2000
+              if remaining_ms
+                dynamic_budget = (remaining_ms * 0.2).to_i
+                sync_timeout_ms = dynamic_budget < 100 ? 0 : [sync_timeout_ms, dynamic_budget].min
               end
+              agent.force_sync(sync_timeout_ms / 1000.0) if sync_timeout_ms.positive?
             end
+          rescue SignalException, SystemExit
+            raise
+          rescue Exception
+            # This boundary never encloses application handler execution.
           end
 
           begin
-            if handler.parameters.length == 1
+            params = handler.parameters
+            has_keywords = params.any? { |type, _| type == :keyreq || type == :key || type == :keyrest }
+
+            if has_keywords
+              handler.call(event: event, context: context)
+            elsif params.length == 1 && (params.first[0] == :req || params.first[0] == :opt)
               handler.call(event)
             else
-              handler.call(event: event, context: context)
+              handler.call(event, context)
             end
           ensure
-            if is_active
-              remaining_ms = context.respond_to?(:get_remaining_time_in_millis) ? context.get_remaining_time_in_millis : 0
-              flush_timeout_ms = options[:flush_timeout_ms] || 1500
-
-              if remaining_ms && remaining_ms > 500
-                flush_timeout_ms = [remaining_ms - 200, flush_timeout_ms].min
-              end
-
-              if remaining_ms > 500 || !context.respond_to?(:get_remaining_time_in_millis)
-                begin
+            begin
+              if agent
+                remaining_ms = context.respond_to?(:get_remaining_time_in_millis) ? context.get_remaining_time_in_millis : nil
+                flush_timeout_ms = options[:flush_timeout_ms] || 1500
+                if remaining_ms.nil? || remaining_ms > 500
+                  flush_timeout_ms = [remaining_ms - 200, flush_timeout_ms].min if remaining_ms
                   agent.force_flush(flush_timeout_ms / 1000.0)
-                rescue StandardError => e
-                  warn "[HyperProbe Lambda] Failed to flush telemetry: #{e.message}"
                 end
-              else
-                warn '[HyperProbe Lambda] Aborting snapshot flush to prevent Lambda timeout.'
               end
+            rescue SignalException, SystemExit
+              raise
+            rescue Exception
+              # Never mask a handler exception with instrumentation cleanup.
             end
           end
         end
+      rescue SignalException, SystemExit
+        raise
+      rescue Exception
+        handler
       end
 
       def stop
@@ -79,11 +75,17 @@ module HyperProbe
         if agent && !agent.agent_disabled?
           begin
             agent.force_flush(1.0)
-          rescue StandardError
+          rescue SignalException, SystemExit
+            raise
+          rescue Exception
             # Best effort
           end
         end
         HyperProbe.shutdown
+      rescue SignalException, SystemExit
+        raise
+      rescue Exception
+        nil
       end
     end
   end

data/lib/hyperprobe/protos/agent_descriptor.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+# Generated by rake proto:descriptor. DO NOT EDIT.
+module Hyperprobe
+  module JavaProto
+    DESCRIPTOR_DATA = "\n\x0b\x61gent.proto\x12\x13hyperprobe.agent.v1\"\x9c\x01\n\x10GetProbesRequest\x12\x10\n\x08\x61gent_id\x18\x01 \x01(\t\x12\x12\n\nservice_id\x18\x02 \x01(\t\x12\x13\n\x0b\x65nvironment\x18\x03 \x01(\t\x12\x12\n\ncommit_sha\x18\x04 \x01(\t\x12\x10\n\x08language\x18\x05 \x01(\t\x12\x15\n\ragent_version\x18\x06 \x01(\t\x12\x10\n\x08hostname\x18\x07 \x01(\t\"\xbc\x01\n\x11GetProbesResponse\x12*\n\x06probes\x18\x01 \x03(\x0b\x32\x1a.hyperprobe.agent.v1.Probe\x12\"\n\x15next_sync_interval_ms\x18\x02 \x01(\x05H\x00\x88\x01\x01\x12=\n\rglobal_config\x18\x03 \x01(\x0b\x32&.hyperprobe.agent.v1.AgentGlobalConfigB\x18\n\x16_next_sync_interval_ms\"U\n\x16SourceMapStatusRequest\x12\x12\n\nservice_id\x18\x01 \x01(\t\x12\x13\n\x0b\x65nvironment\x18\x02 \x01(\t\x12\x12\n\ncommit_sha\x18\x03 \x01(\t\"C\n\x17SourceMapStatusResponse\x12\x13\n\x0bis_uploader\x18\x01 \x01(\x08\x12\x13\n\x0bis_complete\x18\x02 \x01(\x08\"n\n\x0eSourceMapChunk\x12\x12\n\nservice_id\x18\x01 \x01(\t\x12\x13\n\x0b\x65nvironment\x18\x02 \x01(\t\x12\x12\n\ncommit_sha\x18\x03 \x01(\t\x12\x11\n\tfile_name\x18\x04 \x01(\t\x12\x0c\n\x04\x64\x61ta\x18\x05 \x01(\x0c\"!\n\x0eUploadResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08\"[\n\x1cMarkSourceMapCompleteRequest\x12\x12\n\nservice_id\x18\x01 \x01(\t\x12\x13\n\x0b\x65nvironment\x18\x02 \x01(\t\x12\x12\n\ncommit_sha\x18\x03 \x01(\t\"0\n\x1dMarkSourceMapCompleteResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08\"\x85\x03\n\x11\x41gentGlobalConfig\x12\x13\n\x0bredact_keys\x18\x01 \x03(\t\x12\x15\n\rredact_values\x18\x02 \x03(\t\x12\x1d\n\x10max_object_depth\x18\x03 \x01(\x05H\x00\x88\x01\x01\x12\x1d\n\x10max_array_length\x18\x04 \x01(\x05H\x01\x88\x01\x01\x12\x1e\n\x11stack_frame_depth\x18\x05 \x01(\x05H\x02\x88\x01\x01\x12\"\n\x15max_object_properties\x18\x06 \x01(\x05H\x03\x88\x01\x01\x12\x1e\n\x11max_string_length\x18\x07 \x01(\x05H\x04\x88\x01\x01\x12\x1d\n\x10\x63\x61pture_closures\x18\x08 \x01(\x08H\x05\x88\x01\x01\x42\x13\n\x11_max_object_depthB\x13\n\x11_max_array_lengthB\x14\n\x12_stack_frame_depthB\x18\n\x16_max_object_propertiesB\x14\n\x12_max_string_lengthB\x13\n\x11_capture_closures\"\x91\x07\n\x05Probe\x12\n\n\x02id\x18\x01 \x01(\t\x12,\n\x04type\x18\x02 \x01(\x0e\x32\x1e.hyperprobe.agent.v1.ProbeType\x12\x18\n\x10runtime_location\x18\x03 \x01(\t\x12\x14\n\x0cruntime_line\x18\x04 \x01(\x05\x12\"\n\x1asecondary_runtime_location\x18\x05 \x01(\t\x12\x1e\n\x16secondary_runtime_line\x18\x06 \x01(\x05\x12\x11\n\tcondition\x18\x07 \x01(\t\x12\x10\n\x08template\x18\x08 \x01(\t\x12\x13\n\x0bmetric_name\x18\t \x01(\t\x12\x19\n\x11metric_expression\x18\n \x01(\t\x12\x19\n\x11watch_expressions\x18\x0b \x03(\t\x12\x11\n\thit_limit\x18\x0c \x01(\x05\x12\x13\n\x0b\x65xpiry_time\x18\r \x01(\x03\x12\x16\n\x0eruntime_column\x18\x0e \x01(\x05\x12 \n\x18secondary_runtime_column\x18\x0f \x01(\x05\x12\x1e\n\x16\x63orrelation_expression\x18\x10 \x01(\t\x12\x1d\n\x10max_object_depth\x18\x11 \x01(\x05H\x00\x88\x01\x01\x12\x1d\n\x10max_array_length\x18\x12 \x01(\x05H\x01\x88\x01\x01\x12\x1e\n\x11stack_frame_depth\x18\x13 \x01(\x05H\x02\x88\x01\x01\x12\"\n\x15max_object_properties\x18\x14 \x01(\x05H\x03\x88\x01\x01\x12\x1e\n\x11max_string_length\x18\x15 \x01(\x05H\x04\x88\x01\x01\x12$\n\x17should_capture_trace_id\x18\x16 \x01(\x08H\x05\x88\x01\x01\x12\x16\n\tlog_level\x18\x17 \x01(\tH\x06\x88\x01\x01\x12!\n\x14should_log_to_stdout\x18\x18 \x01(\x08H\x07\x88\x01\x01\x12\x1d\n\x10\x63\x61pture_closures\x18\x19 \x01(\x08H\x08\x88\x01\x01\x42\x13\n\x11_max_object_depthB\x13\n\x11_max_array_lengthB\x14\n\x12_stack_frame_depthB\x18\n\x16_max_object_propertiesB\x14\n\x12_max_string_lengthB\x1a\n\x18_should_capture_trace_idB\x0c\n\n_log_levelB\x17\n\x15_should_log_to_stdoutB\x13\n\x11_capture_closures\"W\n\x0eTelemetryBatch\x12\x10\n\x08\x61gent_id\x18\x01 \x01(\t\x12\x33\n\x06\x65vents\x18\x02 \x03(\x0b\x32#.hyperprobe.agent.v1.TelemetryEvent\"\x8a\x01\n\nStackFrame\x12\x15\n\rfunction_name\x18\x01 \x01(\t\x12\x11\n\tfile_name\x18\x02 \x01(\t\x12\x13\n\x0bline_number\x18\x03 \x01(\x05\x12\x15\n\rcolumn_number\x18\x04 \x01(\x05\x12\x17\n\nclass_name\x18\x05 \x01(\tH\x00\x88\x01\x01\x42\r\n\x0b_class_name\"\x8f\x02\n\x0eTelemetryEvent\x12\x10\n\x08probe_id\x18\x01 \x01(\t\x12\x14\n\x0ctimestamp_ms\x18\x02 \x01(\x03\x12\x35\n\x0cstack_frames\x18\x03 \x03(\x0b\x32\x1f.hyperprobe.agent.v1.StackFrame\x12\x1a\n\x12\x63\x61ptured_vars_json\x18\x04 \x01(\t\x12\x1a\n\x12watch_results_json\x18\x05 \x01(\t\x12\x15\n\revaluated_log\x18\x06 \x01(\t\x12\x14\n\x0cmetric_value\x18\x07 \x01(\x01\x12\x15\n\rcapture_error\x18\x08 \x01(\t\x12\x15\n\x08trace_id\x18\t \x01(\tH\x00\x88\x01\x01\x42\x0b\n\t_trace_id\"/\n\x11TelemetryResponse\x12\x1a\n\x12\x66inished_probe_ids\x18\x01 \x03(\t*\x9c\x01\n\tProbeType\x12\x1a\n\x16PROBE_TYPE_UNSPECIFIED\x10\x00\x12\x17\n\x13PROBE_TYPE_SNAPSHOT\x10\x01\x12\x12\n\x0ePROBE_TYPE_LOG\x10\x02\x12\x16\n\x12PROBE_TYPE_COUNTER\x10\x03\x12\x15\n\x11PROBE_TYPE_METRIC\x10\x04\x12\x17\n\x13PROBE_TYPE_DURATION\x10\x05\x32\x99\x04\n\x0b\x41gentBroker\x12Z\n\tGetProbes\x12%.hyperprobe.agent.v1.GetProbesRequest\x1a&.hyperprobe.agent.v1.GetProbesResponse\x12^\n\x0fReportTelemetry\x12#.hyperprobe.agent.v1.TelemetryBatch\x1a&.hyperprobe.agent.v1.TelemetryResponse\x12o\n\x12GetSourceMapStatus\x12+.hyperprobe.agent.v1.SourceMapStatusRequest\x1a,.hyperprobe.agent.v1.SourceMapStatusResponse\x12]\n\x0fUploadSourceMap\x12#.hyperprobe.agent.v1.SourceMapChunk\x1a#.hyperprobe.agent.v1.UploadResponse(\x01\x12~\n\x15MarkSourceMapComplete\x12\x31.hyperprobe.agent.v1.MarkSourceMapCompleteRequest\x1a\x32.hyperprobe.agent.v1.MarkSourceMapCompleteResponseB\tB\x05\x41gentP\x00\x62\x06proto3".b.freeze
+  end
+end

data/lib/hyperprobe/protos/java_messages.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'java'
+require_relative 'agent_descriptor'
+
+begin
+  require_relative '../jars/hyperprobe-grpc.jar'
+  JavaUtilities.get_proxy_class('co.hyperprobe.transport.ProtoCodec')
+rescue Java::JavaLang::LinkageError => e
+  raise LoadError, "Cannot load HyperProbe protobuf codec (Java 11+ required): #{e.message}"
+end
+
+module Hyperprobe
+  module Agent
+    module V1
+    end
+  end
+
+  # Only the SDK's canonical messages are exposed, not Google's Ruby runtime API.
+  module JavaProto
+    CODEC = JavaUtilities.get_proxy_class('co.hyperprobe.transport.ProtoCodec').new(DESCRIPTOR_DATA.to_java_bytes)
+    CLASSES = {}
+
+    class Message
+      class << self
+        attr_accessor :descriptor, :fields
+
+        def decode(bytes)
+          raise TypeError, 'Expected protobuf bytes as a String' unless bytes.is_a?(String)
+          raise ArgumentError, 'Protobuf payload exceeds 4 MiB' if bytes.bytesize > 4 * 1024 * 1024
+
+          from_java(CODEC.decode(descriptor, bytes.to_java_bytes))
+        rescue Java::JavaLang::Exception => e
+          raise ArgumentError, "Invalid protobuf: #{e.message}"
+        end
+
+        def encode(message)
+          raise TypeError, "Expected #{self}" unless message.is_a?(self)
+
+          message.to_proto
+        end
+
+        def from_java(message)
+          result = new
+          message.getAllFields.each do |field, value|
+            decoded = field.isRepeated ? value.map { |item| decode_value(field, item) } : decode_value(field, value)
+            result.public_send("#{field.getName}=", decoded)
+          end
+          result.instance_variable_set(:@unknown_fields, message.getUnknownFields)
+          result
+        end
+
+        def decode_value(field, value)
+          case field.getJavaType.to_s
+          when 'MESSAGE' then CLASSES.fetch(field.getMessageType.getFullName).from_java(value)
+          when 'ENUM' then value.getIndex < 0 ? value.getNumber : value.getName.to_sym
+          when 'BYTE_STRING' then String.from_java_bytes(value.toByteArray)
+          else value
+          end
+        end
+
+        def normalize(field, value)
+          case field.getJavaType.to_s
+          when 'MESSAGE'
+            klass = CLASSES.fetch(field.getMessageType.getFullName)
+            value = klass.new(value) if value.is_a?(Hash)
+            raise TypeError, "Expected #{klass} for #{field.getName}" unless value.is_a?(klass)
+          when 'ENUM'
+            enum = field.getEnumType
+            if value.is_a?(Symbol)
+              entry = enum.findValueByName(value.to_s)
+              raise ArgumentError, "Unknown enum #{value}" unless entry
+              return value
+            end
+            integer!(field, value, 32)
+            entry = enum.findValueByNumber(value)
+            value = entry.getName.to_sym if entry
+          when 'INT', 'LONG'
+            integer!(field, value, field.getJavaType.to_s == 'INT' ? 32 : 64)
+          when 'DOUBLE', 'FLOAT'
+            raise TypeError, "Expected number for #{field.getName}" unless value.is_a?(Numeric) && !value.is_a?(Complex)
+            value = value.to_f
+          when 'BOOLEAN'
+            raise TypeError, "Expected boolean for #{field.getName}" unless value.equal?(true) || value.equal?(false)
+          when 'STRING', 'BYTE_STRING'
+            raise TypeError, "Expected String for #{field.getName}" unless value.is_a?(String)
+            value = field.getJavaType.to_s == 'STRING' ? value.encode(Encoding::UTF_8) : value.b
+            raise ArgumentError, 'Invalid UTF-8 protobuf string' unless value.valid_encoding?
+            value = value.dup.freeze
+          else
+            raise ArgumentError, "Unsupported canonical field #{field.getName}"
+          end
+          value
+        end
+
+        def integer!(field, value, bits)
+          raise TypeError, "Expected Integer for #{field.getName}" unless value.is_a?(Integer)
+          raise RangeError, "Out of range for #{field.getName}" unless value >= -(2**(bits - 1)) && value < 2**(bits - 1)
+        end
+
+        def java_value(field, value)
+          case field.getJavaType.to_s
+          when 'MESSAGE' then value.to_java_message
+          when 'ENUM'
+            enum = field.getEnumType
+            value.is_a?(Symbol) ? enum.findValueByName(value.to_s) : enum.findValueByNumberCreatingIfUnknown(value)
+          when 'BYTE_STRING' then CODEC.bytes(value.to_java_bytes)
+          when 'STRING' then value.to_java(:string)
+          when 'INT' then value.to_java(:int)
+          when 'LONG' then value.to_java(:long)
+          when 'FLOAT' then value.to_java(:float)
+          when 'DOUBLE' then value.to_java(:double)
+          when 'BOOLEAN' then value.to_java(:boolean)
+          end
+        end
+      end
+
+      def initialize(values = {})
+        raise ArgumentError, 'Expected a field Hash' unless values.is_a?(Hash)
+
+        @values = {}
+        values.each do |name, value|
+          key = name.to_s
+          raise ArgumentError, "Unknown field #{key}" unless self.class.fields.key?(key)
+          public_send("#{key}=", value) unless value.nil?
+        end
+      end
+
+      def to_java_message
+        builder = CODEC.builder(self.class.descriptor)
+        builder.mergeUnknownFields(@unknown_fields) if @unknown_fields
+        @values.each do |name, value|
+          field = self.class.fields.fetch(name)
+          if field.isRepeated
+            # Arrays remain mutable; scalar setters already normalize and freeze strings.
+            value.each { |item| builder.addRepeatedField(field, self.class.java_value(field, self.class.normalize(field, item))) }
+          else
+            builder.setField(field, self.class.java_value(field, value))
+          end
+        end
+        builder.build
+      end
+
+      def to_proto
+        String.from_java_bytes(to_java_message.toByteArray)
+      end
+
+      def serialized_size
+        to_java_message.getSerializedSize
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && to_java_message == other.to_java_message
+      end
+      alias eql? ==
+
+      def hash
+        to_java_message.hashCode
+      end
+    end
+
+    CODEC.getFile.getEnumTypes.each do |enum|
+      mod = Module.new
+      enum.getValues.each { |value| mod.const_set(value.getName, value.getNumber) }
+      Agent::V1.const_set(enum.getName, mod)
+    end
+
+    CODEC.getFile.getMessageTypes.each do |descriptor|
+      klass = Class.new(Message)
+      klass.descriptor = descriptor
+      klass.fields = descriptor.getFields.each_with_object({}) { |field, fields| fields[field.getName] = field }.freeze
+      CLASSES[descriptor.getFullName] = klass
+      Agent::V1.const_set(descriptor.getName, klass)
+      klass.fields.each do |name, field|
+        klass.define_method(name) do
+          return @values[name] if @values.key?(name)
+          return @values[name] = [] if field.isRepeated
+          return nil if field.getJavaType.to_s == 'MESSAGE'
+
+          self.class.decode_value(field, field.getDefaultValue)
+        end
+        klass.define_method("#{name}=") do |value|
+          if value.nil? && field.hasPresence
+            @values.delete(name)
+          elsif field.isRepeated
+            raise TypeError, "Expected Array for #{name}" unless value.is_a?(Array)
+            @values[name] = value.map { |item| self.class.normalize(field, item) }
+          else
+            @values[name] = self.class.normalize(field, value)
+          end
+        end
+        if field.hasPresence
+          klass.define_method("has_#{name}?") { @values.key?(name) }
+        end
+      end
+    end
+    CLASSES.freeze
+  end
+end

data/lib/hyperprobe/protos.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
-protos_dir = File.expand_path('protos', __dir__)
-$LOAD_PATH.unshift(protos_dir) unless $LOAD_PATH.include?(protos_dir)
-
-require 'agent_pb'
-
-if RUBY_PLATFORM !~ /java/
+if RUBY_PLATFORM =~ /java/
+  require_relative 'protos/java_messages'
+else
+  protos_dir = File.expand_path('protos', __dir__)
+  $LOAD_PATH.unshift(protos_dir) unless $LOAD_PATH.include?(protos_dir)
+  require 'agent_pb'
   begin
     require 'agent_services_pb'
   rescue LoadError
-    # JRuby or environments without C-grpc gem
+    # Environments without the C-grpc gem can still use the messages.
   end
 end

data/lib/hyperprobe/railtie.rb

@@ -10,6 +10,12 @@ module HyperProbe
         if enabled && has_service_id
           HyperProbe.start
         end
+
+        if defined?(::Spring) && ::Spring.respond_to?(:after_fork)
+          ::Spring.after_fork do
+            HyperProbe.after_fork
+          end
+        end
       end
     end
   end

data/lib/hyperprobe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HyperProbe
-  VERSION = '1.2.27-1'
+  VERSION = '1.2.27.pre.3'
 end

data/lib/hyperprobe.rb

@@ -1,23 +1,38 @@
 # frozen_string_literal: true
 
-require_relative 'hyperprobe/version'
-require_relative 'hyperprobe/protos'
-require_relative 'hyperprobe/core/logger'
-require_relative 'hyperprobe/agent'
-require_relative 'hyperprobe/lambda'
-require_relative 'hyperprobe/railtie' if defined?(::Rails::Railtie)
+begin
+  require_relative 'hyperprobe/version'
+  require_relative 'hyperprobe/protos'
+  require_relative 'hyperprobe/core/logger'
+  require_relative 'hyperprobe/agent'
+  require_relative 'hyperprobe/lambda'
+  require_relative 'hyperprobe/railtie' if defined?(::Rails::Railtie)
+rescue SignalException, SystemExit
+  raise
+rescue Exception
+  # Missing native dependencies or a broken JVM transport disable only the SDK.
+  module HyperProbe
+    LOAD_FAILED = true
+  end
+end
 
 module HyperProbe
   @instance = nil
   @mutex = Mutex.new
+  @owner_pid = Process.pid
 
   class << self
     def logger(namespace = 'hyperprobe:agent')
       Core::Logger.get_logger(namespace)
     end
     def start(options = {})
-      @mutex.synchronize do
+      reset_after_fork
+      return nil if defined?(LOAD_FAILED) || @fork_disabled
+      return nil unless @mutex.try_lock
+      locked = true
+      begin
         return @instance if @instance
+        @stop_requested = false
 
         if ENV['HYPERPROBE_DISABLED']&.strip&.upcase == 'YES'
           puts '[HyperProbe] Explicitly disabled via ENV["HYPERPROBE_DISABLED"].'
@@ -60,7 +75,7 @@ module HyperProbe
           raw_jruby_ver = defined?(JRUBY_VERSION) ? JRUBY_VERSION.to_s : '0'
           jruby_ver = Gem::Version.new(raw_jruby_ver)
           if jruby_ver < Gem::Version.new('9.3.0.0')
-            warn "\e[1m\e[33m⚠️  [HyperProbe] Unsupported JRuby version (#{raw_jruby_ver}). HyperProbe requires JRuby 9.3+ or 9.4+.\e[0m"
+            warn "[HyperProbe] Unsupported JRuby version (#{raw_jruby_ver}); JRuby 9.3+ is required."
             return nil
           end
 
@@ -69,6 +84,11 @@ module HyperProbe
             return nil
           end
 
+          unless jruby_scope_preservation_enabled?
+            warn '[HyperProbe] Agent disabled: compiled JRuby probes require -J-Djruby.ir.passes=AddCallProtocolInstructions,AddMissingInitsPass and -J-Djruby.ir.jit.passes=AddCallProtocolInstructions,AddMissingInitsPass at process startup. These preserve locals with JIT enabled; benchmark their application-wide cost before deployment.'
+            return nil
+          end
+
           begin
             require 'java'
             java_ver_str = java.lang.System.getProperty('java.specification.version') || '11'
@@ -88,49 +108,111 @@ module HyperProbe
           end
         end
 
-        @instance = Agent.new(opts)
+        if opts.delete(:defer_start) || opts.delete(:deferStart)
+          @deferred_options = opts
+          return nil
+        end
+        @native_owner_pid = Process.pid
+        candidate = Agent.new(opts)
+        return nil if candidate.is_shutdown
+        if @stop_requested
+          candidate.shutdown
+          return nil
+        end
+        @instance = candidate
+        puts "[HyperProbe] Ruby agent successfully started (Version: #{VERSION}, ID: #{@instance.agent_id}, PID: #{@instance.owner_pid})."
         @instance
+      ensure
+        @mutex.unlock if locked
       end
+    rescue SignalException, SystemExit
+      candidate&.shutdown
+      raise
+    rescue Exception
+      nil
     end
 
     def shutdown
-      @mutex.synchronize do
-        return unless @instance
-
-        @instance.shutdown
+      reset_after_fork
+      @stop_requested = true
+      unless @mutex.try_lock
+        defer_shutdown
+        return nil
+      end
+      begin
+        inst = @instance
         @instance = nil
+      ensure
+        @mutex.unlock
       end
+      return unless inst
+      inst.shutdown
+      puts '[HyperProbe] Ruby agent successfully shut down.'
+    rescue ThreadError
+      defer_shutdown
+      nil
+    rescue SignalException, SystemExit
+      raise
+    rescue Exception
+      nil
     end
 
     def instance
-      @mutex.synchronize { @instance }
+      @instance
     end
 
     def after_fork
       return unless Process.respond_to?(:fork) && !defined?(JRUBY_VERSION)
 
-      @mutex.synchronize do
-        @instance&.after_fork
+      return @instance if @owner_pid == Process.pid
+      reset_after_fork
+      if @fork_disabled
+        warn '[HyperProbe] Inherited agent disabled. Use defer_start: true before preloading and after_fork in each worker.'
+        return nil
       end
+      options = @deferred_options
+      @deferred_options = nil
+      start(options) if options
+    rescue SignalException, SystemExit
+      raise
+    rescue Exception
+      nil
     end
 
     def wrap_lambda(options = {}, &handler)
+      return handler if defined?(LOAD_FAILED)
       Lambda.wrap(options, &handler)
+    rescue SignalException, SystemExit
+      raise
+    rescue Exception
+      handler
     end
 
     def stop_lambda
-      Lambda.stop
+      Lambda.stop if defined?(Lambda)
+    rescue SignalException, SystemExit
+      raise
+    rescue Exception
+      nil
     end
 
     def jruby_debug_enabled?
       begin
         require 'java'
-        return true if Java::OrgJrubyUtilCli::Options::DEBUG_FULLTRACE.load == true
+        return Java::OrgJruby::RubyInstanceConfig.FULL_TRACE_ENABLED == true
       rescue StandardError, ScriptError, NameError
       end
 
-      opts = ENV['JRUBY_OPTS'] || ''
-      opts.include?('--debug') || opts.include?('-Xdebug.fullTrace=true')
+      false
+    end
+
+    def jruby_scope_preservation_enabled?
+      require 'java'
+      required = 'AddCallProtocolInstructions,AddMissingInitsPass'
+      Java::OrgJrubyUtilCli::Options::IR_COMPILER_PASSES.load.to_s == required &&
+        Java::OrgJrubyUtilCli::Options::IR_JIT_PASSES.load.to_s == required
+    rescue StandardError, ScriptError
+      false
     end
 
     def valid_broker_url?(url)
@@ -149,5 +231,52 @@ module HyperProbe
       # Raw gRPC target
       !raw.include?('://') && !raw.include?('/') && !raw.include?('?')
     end
+
+    private
+
+    def defer_shutdown
+      Thread.new do
+        inst = @mutex.synchronize do
+          current = @instance
+          @instance = nil
+          current
+        end
+        inst&.shutdown
+      rescue Exception
+        # Cleanup waits only on an agent worker, never on an application thread.
+        nil
+      end
+    end
+
+    def reset_after_fork
+      return if @owner_pid == Process.pid
+      @owner_pid = Process.pid
+      @mutex = Mutex.new
+      if @native_owner_pid
+        @fork_disabled = true
+        @instance&.after_fork
+        @instance = nil
+      end
+    end
+
+    def puts(message)
+      notice($stdout, message)
+    end
+
+    def warn(message)
+      notice($stderr, message)
+    end
+
+    def notice(stream, message)
+      if IO === stream
+        IO.instance_method(:write_nonblock).bind(stream).call("#{message}\n", exception: false)
+      elsif defined?(StringIO) && StringIO === stream
+        StringIO.instance_method(:write).bind(stream).call("#{message}\n")
+      end
+    rescue SignalException, SystemExit
+      raise
+    rescue Exception
+      nil
+    end
   end
 end