bitfab 0.33.3 → 0.33.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44ebaac53c01dd84f179de5559eb3f00836c6c1a51f15520b8f10085bcfd6021
-  data.tar.gz: b7255113aef3706aefd3a1017520f24e6127503418965a0db23e70573fdd3d0e
+  metadata.gz: 12cae09488f9200115e768e31661e55be850acc2dbcf2b53eece9c4ab4d59ca2
+  data.tar.gz: 3242cb27cbd71d15094bc4024cb914a494eefa2eeee317e1d45c8ba77c77f4a0
 SHA512:
-  metadata.gz: de1b1c86dc8660477b87632d766e6f8fdf858d682248c9bd53d024fb3b423acc18d02d877ff567344e5a80aa686d0ad3e72bb02e8cc7dd099612e28ccdc02ad2
-  data.tar.gz: bb0ea7013f448acffa4644a359c0c38198ce9c74caf2b77c3d4d4c80a3f5b6f6f0bd73591ffd653b97c99af6518bc0c12460d69ac65314faf5d047541d731d1c
+  metadata.gz: 11f4111de6c94527b2f4b14757b50ccaddea211d3366bf1a5241e8e7e0ffa065138a84fa7f6db84baaec926cfeb9754fe7024a090b297ecb35e7916a1fc517f1
+  data.tar.gz: 880b440e2610064045ff1e753d65167c46be2a7220897aa0631b739e24affec2e99cd05de12acf2d39f162474d8fbec6ff13b614f60c6390529395ad2478e4ab

data/lib/bitfab/client.rb

@@ -243,12 +243,23 @@ module Bitfab
     # Execute a block inside a span context, sending trace data on completion.
     # Called by Traceable, not intended for direct use.
     def execute_span(trace_function_key:, span_name:, span_type:, function_name:, args:, kwargs:,
-      mock_on_replay: false)
+      capture_when: "always", mock_on_replay: false)
       # Decide at CALL time, not construction. The key may be set after the
       # client is built (env loaded later), so re-checking per call lets a
       # late-resolved key take effect.
       return yield unless tracing_enabled?
 
+      resolved_capture_when = capture_when.to_s
+      unless %w[always nested].include?(resolved_capture_when)
+        Bitfab.warn_once(
+          "invalid-capture-when:#{trace_function_key}",
+          "unknown capture_when value #{capture_when.inspect}; defaulting to \"always\". " \
+          "Valid values: \"always\", \"nested\"."
+        )
+        resolved_capture_when = "always"
+      end
+      return yield if resolved_capture_when == "nested" && SpanContext.current.nil?
+
       # Span setup runs before the user's block. Tracing is a side-channel, so
       # if anything here raises (id generation, trace-state bookkeeping, a
       # malformed replay mock tree) the user's method must still run. On failure
@@ -892,12 +903,15 @@ module Bitfab
     # @param method_name [Symbol] the method to wrap
     # @param name [String, nil] explicit span name (defaults to method name)
     # @param type [String] span type
+    # @param capture_when [String, Symbol] "always" to allow a root trace, or
+    #   "nested" to capture only when another Bitfab span is active. Unknown
+    #   values warn once and default to "always"
     # @param mock_on_replay [Boolean] mark this span for the default "marked" mock strategy
-    def wrap(klass, method_name, name: nil, type: "custom", mock_on_replay: false)
+    def wrap(klass, method_name, name: nil, type: "custom", capture_when: "always", mock_on_replay: false)
       Bitfab::Traceable.wrap(
         klass, method_name,
         trace_function_key: @trace_function_key,
-        name:, type:, mock_on_replay:,
+        name:, type:, capture_when:, mock_on_replay:,
         client: @client
       )
     end

data/lib/bitfab/traceable.rb

@@ -38,6 +38,9 @@ module Bitfab
     # @param trace_function_key [String] the trace function key
     # @param name [String, nil] explicit span name (defaults to method name)
     # @param type [String] span type: llm, agent, function, guardrail, handoff, custom
+    # @param capture_when [String, Symbol] "always" to allow a root trace, or
+    #   "nested" to capture only when another Bitfab span is active. Unknown
+    #   values warn once and default to "always"
     # @param mock_on_replay [Boolean] mark this span for the default "marked" mock strategy.
     #   When true, `client.replay(...)` returns this span's
     #   historical output instead of executing the wrapped method.
@@ -48,7 +51,7 @@ module Bitfab
     #   preserve the bound client through the fluent wrapper, matching Python's
     #   `BitfabFunction.span()` and TypeScript's `BitfabFunction.withSpan()`.
     def self.wrap(klass, method_name, trace_function_key:, name: nil, type: "custom",
-      mock_on_replay: false, client: nil)
+      capture_when: "always", mock_on_replay: false, client: nil)
       span_name = name || method_name.to_s
       method_name_str = method_name.to_s
       bound_client = client
@@ -63,6 +66,7 @@ module Bitfab
             function_name: method_name_str,
             args:,
             kwargs:,
+            capture_when:,
             mock_on_replay:) do
             super(*args, **kwargs, &block)
           end
@@ -132,10 +136,14 @@ module Bitfab
       # @param trace_function_key [String, nil] trace function key (overrides class-level bitfab_function)
       # @param name [String, nil] explicit span name (defaults to method name)
       # @param type [String] span type: llm, agent, function, guardrail, handoff, custom
+      # @param capture_when [String, Symbol] "always" to allow a root trace, or
+      #   "nested" to capture only when another Bitfab span is active. Unknown
+      #   values warn once and default to "always"
       # @param mock_on_replay [Boolean] mark this span for the default "marked" mock strategy.
       #   When true, `client.replay(...)` returns this span's
       #   historical output instead of executing the wrapped method.
-      def bitfab_span(method_name, trace_function_key: nil, name: nil, type: "custom", mock_on_replay: false)
+      def bitfab_span(method_name, trace_function_key: nil, name: nil, type: "custom",
+        capture_when: "always", mock_on_replay: false)
         trace_function_key ||= @bitfab_function_key
         unless trace_function_key
           raise "No trace function key provided. Pass `trace_function_key:` to `bitfab_span` " \
@@ -144,7 +152,9 @@ module Bitfab
 
         # If the method already exists (inline or after-method style), wrap it immediately
         if method_defined?(method_name) || private_method_defined?(method_name)
-          _bitfab_wrap_method(method_name, trace_function_key:, name:, type:, mock_on_replay:)
+          _bitfab_wrap_method(
+            method_name, trace_function_key:, name:, type:, capture_when:, mock_on_replay:
+          )
         else
           # Method doesn't exist yet (before-method style) - register for method_added hook
           @_bitfab_pending_spans ||= {}
@@ -152,6 +162,7 @@ module Bitfab
             trace_function_key:,
             name:,
             type:,
+            capture_when:,
             mock_on_replay:
           }
         end
@@ -167,7 +178,8 @@ module Bitfab
         _bitfab_wrap_method(method_name, **config)
       end
 
-      def _bitfab_wrap_method(method_name, trace_function_key:, name: nil, type: "custom", mock_on_replay: false)
+      def _bitfab_wrap_method(method_name, trace_function_key:, name: nil, type: "custom",
+        capture_when: "always", mock_on_replay: false)
         span_name = name || method_name.to_s
         method_name_str = method_name.to_s
 
@@ -185,6 +197,7 @@ module Bitfab
               function_name: method_name_str,
               args:,
               kwargs:,
+              capture_when:,
               mock_on_replay:) do
               super(*args, **kwargs, &block)
             end

data/lib/bitfab/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.33.3
+  version: 0.33.4
 platform: ruby
 authors:
 - Harvest Team