bitfab 0.51.2 → 0.51.4

data/lib/bitfab/traceable.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "subtree"
+
 module Bitfab
   # Mixin for declarative span tracing on instance methods.
   #
@@ -67,7 +69,9 @@ module Bitfab
             args:,
             kwargs:,
             capture_when:,
-            mock_on_replay:) do
+            mock_on_replay:,
+            explicit_span_receiver: self,
+            explicit_span_method_name: method_name) do
             super(*args, **kwargs, &block)
           end
         end
@@ -78,6 +82,137 @@ module Bitfab
       klass.prepend(wrapper)
     end
 
+    # Wrap an existing method with experimental whole-subtree tracing.
+    # The root records with the requested type; first-party Ruby methods called
+    # beneath it record automatically as function spans.
+    def self.trace(klass, method_name, trace_function_key:, name: nil, type: "custom",
+      max_depth: Subtree::DEFAULT_MAX_DEPTH, max_spans: Subtree::DEFAULT_MAX_SPANS,
+      exclude: [], include_wrappers: false, client: nil)
+      source = source_of(klass, method_name)
+      capture_config = Subtree.prepare(root_source: source, exclude:)
+      span_name = name || method_name.to_s
+      method_name_str = method_name.to_s
+      bound_client = client
+
+      wrapper = Module.new do
+        define_method(method_name) do |*args, **kwargs, &block|
+          if Subtree.active_trace?(trace_function_key)
+            next super(*args, **kwargs, &block)
+          end
+
+          target_client = bound_client || Bitfab.client
+          target_client.send(
+            :execute_span,
+            trace_function_key:,
+            span_name:,
+            span_type: type,
+            function_name: method_name_str,
+            args:,
+            kwargs:,
+            independent_root: true
+          ) do
+            Subtree.capture(
+              client: target_client,
+              trace_function_key:,
+              config: capture_config,
+              max_depth:,
+              max_spans:,
+              include_wrappers:,
+              root_receiver: self,
+              root_method_name: method_name
+            ) { super(*args, **kwargs, &block) }
+          end
+        end
+      end
+
+      wrapper.instance_variable_set(:@bitfab_span_method, method_name_str)
+      wrapper.instance_variable_set(:@bitfab_span_key, trace_function_key)
+      preserve_visibility(klass, wrapper, method_name)
+      klass.prepend(wrapper)
+    end
+
+    # Configure an existing method only when it is discovered beneath a
+    # bitfab_trace root. Outside subtree capture the method runs unchanged.
+    def self.node(klass, method_name, name: nil, type: "custom", capture: true,
+      test_run_id: nil, mock_on_replay: false, finalize: nil, client: nil)
+      validate_node_options!(capture:, mock_on_replay:)
+      span_name = name || method_name.to_s
+      method_name_str = method_name.to_s
+      bound_client = client
+
+      wrapper = Module.new do
+        define_method(method_name) do |*args, **kwargs, &block|
+          session = Subtree.current_session
+          if !session || (bound_client && !session.client.equal?(bound_client))
+            next super(*args, **kwargs, &block)
+          end
+
+          unless capture
+            next Subtree.with_suppressed_node(receiver: self, method_name:) do
+              super(*args, **kwargs, &block)
+            end
+          end
+
+          if session.excluded?(method_name)
+            next Subtree.with_suppressed_node(receiver: self, method_name:, sessions: [session]) do
+              super(*args, **kwargs, &block)
+            end
+          end
+
+          unless session.reserve_node
+            next Subtree.with_suppressed_node(receiver: self, method_name:, sessions: [session]) do
+              super(*args, **kwargs, &block)
+            end
+          end
+
+          session.client.send(
+            :execute_span,
+            trace_function_key: session.trace_function_key,
+            span_name:,
+            span_type: type,
+            function_name: method_name_str,
+            args:,
+            kwargs:,
+            capture_when: "nested",
+            mock_on_replay:,
+            explicit_span_receiver: self,
+            explicit_span_method_name: method_name,
+            test_run_id:,
+            finalize:
+          ) { super(*args, **kwargs, &block) }
+        end
+      end
+
+      preserve_visibility(klass, wrapper, method_name)
+      klass.prepend(wrapper)
+    end
+
+    def self.source_of(klass, method_name)
+      path, line = klass.instance_method(method_name).source_location || [nil, nil]
+      [path, line, method_name]
+    end
+    private_class_method :source_of
+
+    def self.preserve_visibility(klass, wrapper, method_name)
+      visibility = if klass.private_method_defined?(method_name)
+        :private
+      elsif klass.protected_method_defined?(method_name)
+        :protected
+      else
+        :public
+      end
+      wrapper.send(visibility, method_name)
+    end
+    private_class_method :preserve_visibility
+
+    def self.validate_node_options!(capture:, mock_on_replay:)
+      return unless !capture && mock_on_replay
+
+      raise ArgumentError,
+        "bitfab_node(capture: false) cannot use mock_on_replay: true because an uncaptured node has no recorded output."
+    end
+    private_class_method :validate_node_options!
+
     # Resolve the trace function key a traced method records spans under, or
     # nil if the method carries no Bitfab span wrapper. Walks the receiver's
     # ancestor chain for the wrapper module that bitfab_span / Traceable.wrap
@@ -168,14 +303,62 @@ module Bitfab
         end
       end
 
+      # EXPERIMENTAL. Trace a method and every first-party Ruby method it calls.
+      # Descendants require no Bitfab declarations and record as function spans.
+      def bitfab_trace(method_name, trace_function_key: nil, name: nil, type: "custom",
+        max_depth: Subtree::DEFAULT_MAX_DEPTH, max_spans: Subtree::DEFAULT_MAX_SPANS,
+        exclude: [], include_wrappers: false)
+        trace_function_key ||= @bitfab_function_key
+        unless trace_function_key
+          raise "No trace function key provided. Pass `trace_function_key:` to `bitfab_trace` " \
+                "or call `bitfab_function 'my-key'` before using `bitfab_trace`."
+        end
+
+        config = {
+          trace_function_key:,
+          name:,
+          type:,
+          max_depth:,
+          max_spans:,
+          exclude:,
+          include_wrappers:
+        }
+        if method_defined?(method_name) || private_method_defined?(method_name)
+          _bitfab_trace_method(method_name, **config)
+        else
+          @_bitfab_pending_traces ||= {}
+          @_bitfab_pending_traces[method_name] = config
+        end
+      end
+
+      # EXPERIMENTAL. Configure one method discovered beneath bitfab_trace.
+      # The node inherits the active trace key and never traces by itself.
+      def bitfab_node(method_name, name: nil, type: "custom", capture: true,
+        test_run_id: nil, mock_on_replay: false, finalize: nil)
+        Traceable.send(:validate_node_options!, capture:, mock_on_replay:)
+        config = {name:, type:, capture:, test_run_id:, mock_on_replay:, finalize:}
+        if method_defined?(method_name) || private_method_defined?(method_name)
+          _bitfab_node_method(method_name, **config)
+        else
+          @_bitfab_pending_nodes ||= {}
+          @_bitfab_pending_nodes[method_name] = config
+        end
+      end
+
       private
 
       def method_added(method_name)
         super
-        return unless defined?(@_bitfab_pending_spans) && @_bitfab_pending_spans&.key?(method_name)
-
-        config = @_bitfab_pending_spans.delete(method_name)
-        _bitfab_wrap_method(method_name, **config)
+        if defined?(@_bitfab_pending_spans) && @_bitfab_pending_spans&.key?(method_name)
+          config = @_bitfab_pending_spans.delete(method_name)
+          _bitfab_wrap_method(method_name, **config)
+        elsif defined?(@_bitfab_pending_traces) && @_bitfab_pending_traces&.key?(method_name)
+          config = @_bitfab_pending_traces.delete(method_name)
+          _bitfab_trace_method(method_name, **config)
+        elsif defined?(@_bitfab_pending_nodes) && @_bitfab_pending_nodes&.key?(method_name)
+          config = @_bitfab_pending_nodes.delete(method_name)
+          _bitfab_node_method(method_name, **config)
+        end
       end
 
       def _bitfab_wrap_method(method_name, trace_function_key:, name: nil, type: "custom",
@@ -198,7 +381,9 @@ module Bitfab
               args:,
               kwargs:,
               capture_when:,
-              mock_on_replay:) do
+              mock_on_replay:,
+              explicit_span_receiver: self,
+              explicit_span_method_name: method_name) do
               super(*args, **kwargs, &block)
             end
           end
@@ -208,6 +393,68 @@ module Bitfab
         wrapper.instance_variable_set(:@bitfab_span_key, trace_function_key)
         prepend(wrapper)
       end
+
+      def _bitfab_trace_method(method_name, trace_function_key:, name: nil, type: "custom",
+        max_depth: Subtree::DEFAULT_MAX_DEPTH, max_spans: Subtree::DEFAULT_MAX_SPANS,
+        exclude: [], include_wrappers: false)
+        source = Traceable.send(:source_of, self, method_name)
+        capture_config = Subtree.prepare(root_source: source, exclude:)
+        span_name = name || method_name.to_s
+        method_name_str = method_name.to_s
+
+        wrapper = Module.new do
+          define_method(method_name) do |*args, **kwargs, &block|
+            if Subtree.active_trace?(trace_function_key)
+              next super(*args, **kwargs, &block)
+            end
+
+            client = Bitfab.client_or_nil
+            return super(*args, **kwargs, &block) unless client
+
+            client.send(
+              :execute_span,
+              trace_function_key:,
+              span_name:,
+              span_type: type,
+              function_name: method_name_str,
+              args:,
+              kwargs:,
+              independent_root: true
+            ) do
+              Subtree.capture(
+                client:,
+                trace_function_key:,
+                config: capture_config,
+                max_depth:,
+                max_spans:,
+                include_wrappers:,
+                root_receiver: self,
+                root_method_name: method_name
+              ) { super(*args, **kwargs, &block) }
+            end
+          end
+        end
+
+        wrapper.instance_variable_set(:@bitfab_span_method, method_name_str)
+        wrapper.instance_variable_set(:@bitfab_span_key, trace_function_key)
+        Traceable.send(:preserve_visibility, self, wrapper, method_name)
+        prepend(wrapper)
+      end
+
+      def _bitfab_node_method(method_name, name: nil, type: "custom", capture: true,
+        test_run_id: nil, mock_on_replay: false, finalize: nil)
+        Traceable.node(
+          self,
+          method_name,
+          name:,
+          type:,
+          capture:,
+          test_run_id:,
+          mock_on_replay:,
+          finalize:,
+          client: nil
+        )
+      end
     end
   end
 end

data/lib/bitfab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bitfab
-  VERSION = "0.51.2"
+  VERSION = "0.51.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.51.2
+  version: 0.51.4
 platform: ruby
 authors:
 - Harvest Team
@@ -156,6 +156,7 @@ files:
 - lib/bitfab/replay_registry.rb
 - lib/bitfab/serialize.rb
 - lib/bitfab/span_context.rb
+- lib/bitfab/subtree.rb
 - lib/bitfab/timestamp.rb
 - lib/bitfab/traceable.rb
 - lib/bitfab/transport.rb